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TERMS AND CONDITIONS OF SALE AND LICENSE OF TANDY COMPUTER EQUIPMENT AND SOFTWARE PURCHASED 
FROM RADIO SHACK COMPANY-OWNED COMPUTER CENTERS, RETAIL STORES AND, RADIO SHACK FRANCHISEES OR 
DEALERS AT THEIR AUTHORIZED LOCATIONS 


LIMITED WARRANTY 
CUSTOMER OBLIGATIONS 


A. CUSTOMER assumes full responsibility that this computer hardware purchased (the ‘‘Equipment’’), and any copies of software included with the 
Equipment or licensed separately (the ‘‘Software’’) meets the specifications, capacity, capabilities, versatility, and other requirements of CUSTOMER. 

B. CUSTOMER assumes full responsibility for the condition and effectiveness of the operating environment in which the Equipment and Software are to 
function, and for its installation. 


LIMITED WARRANTIES AND CONDITIONS OF SALE 


A. Fora period of ninety (90) calendar days from the date of the Radio Shack sales document received upon purchase of the Equipment. RADIO SHACK 
warrants to the original CUSTOMER that the Equipment and the medium upon which the Software is stored is free from manufacturing defects. This 
warranty is only applicable to purchases of Tandy Equipment by the original customer from Radio Shack company-owned computer centers, 
retail stores, and Radio Shack franchisees and dealers at their authorized locations. The warranty is void if the Equipment’s case or cabinet has 
been opened, or if the Equipment or Software has been subjected to improper or abnormal use. If a manufacturing defect is discovered during the 
stated warranty period, the defective Equipment must be returned to a Radio Shack Computer Center, a Radio Shack retail store, a participating 
Radio Shack franchisee or a participating Radio Shack dealer for repair, along with a copy of the sales document or lease agreement. The original 
CUSTOMER’S sole and exclusive remedy in the event of a defect is limited to the correction of the defect by repair, replacement, or refund of the 
purchase price, at RADIO SHACK’S election and sole expense. RADIO SHACK has no obligation to replace or repair expendable items. 

B. RADIO SHACK makes no warranty as to the design, capability, capacity, or suitability for use of the Software, except as provided in this paragraph. 
Software is licensed on an ‘‘AS IS’’ basis, without warranty. The original CUSTOMER’S exclusive remedy, in the event of a Software manufacturing 
defect, is its repair or replacement within thirty (30) calendar days of the date of the Radio Shack sales document received upon license of the 
Software. The defective Software shall be returned to a Radio Shack Computer Center, a Radio Shack retail store, a participating Radio Shack 
franchisee or Radio Shack dealer along with the sales document. 

C. xcept as provided herein no employee, agent, franchisee, dealer or other person is authorized to give any warranties of any nature on behalf of 
RADIO SHACK. 

D. EXCEPT AS PROVIDED HEREIN, RADIO SHACK MAKES NO EXPRESS WARRANTIES, AND ANY IMPLIEi WARRANTY OF MERCHANTABILITY OR 
FITNESS FOR A PARTICULAR PURPOSE IS LIMITED IN ITS DURATION TO THE DURATION OF THE WRITTEN LIMITED WARRANTIES SET FORTH 
HEREIN. 

E. Some states do not allow limitations on how long an implied warranty lasts, so the above limitation(s) may not apply to CUSTOMER. 


LIMITATION OF LIABILITY 


A. EXCEPT AS PROVIDED HEREIN, RADIO SHACK SHALL HAVE NO LIABILITY OR RESPONSIBILITY TO CUSTOMER OR ANY OTHER PERSON OR 

ENTITY WITH RESPECT TO ANY LIABILITY, LOSS OR DAMAGE CAUSED OR ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY 

“EQUIPMENT” OR “SOFTWARE” SOLD, LEASED, LICENSED OR FURNISHED BY RADIO SHACK, INCLUDING, BUT NOT LIMITED TO, ANY 

INTERRUPTION OF SERVICE, LOSS OF BUSINESS OR ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OR 

OPERATION OF THE “EQUIPMENT” OR “SOFTWARE.” IN NO EVENT SHALL RADIO SHACK BE LIABLE FOR LOSS OF PROFITS, OR ANY 

INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY BREACH OF THIS WARRANTY OR IN ANY MANNER ARISING OUT OF 

OR CONNECTED WITH THE SALE, LEASE, LICENSE, USE OR ANTICIPATED USE OF THE “EQUIPMENT” OR “SOFTWARE.” 

NOTWITHSTANDING THE ABOVE LIMITATIONS AND WARRANTIES, RADIO SHACK’S LIABILITY HEREUNDER FOR DAMAGES INCURRED BY 

CUSTOMER OR OTHERS SHALL NOT EXCEED THE AMOUNT PAID BY CUSTO‘AER FOR THE PARTICULAR “EQUIPMENT” OR “SOFTWARE” 

INVOLVED. 

RADIO SHACK shall not be liable for any damages caused by delay in delivering or furnishing Equipment and/or Software. 

No action arising out of any claimed breach of this Warranty or transactions under this Warranty may be brought more than two (2) years after the 

cause of action has accrued or more than four (4) years after the date of the Radio Shack sales document for the Equipment or Software, whichever 

first occurs. 

D. Some states do not allow the limitation or exclusion of incidental or consequential damages, so the above limitation(s) or exclusion(s) may not apply 
to CUSTOMER. 


SOFTWARE LICENSE 


RADIO SHACK grants to CUSTOMER a non-exclusive, paid-up license to use the TANDY Software on one computer, subject to the following provisions: 

A. Except as otherwise provided in this Software License, applicable copyright laws shall apply to the Software. 

B. Title to the medium on which the Software is recorded (cassette and/or diskette) or stored (ROM) is transferred to CUSTOMER, but not title to the 
Software. 

C. CUSTOMER may use Software on a multiuser or network system only if either, the Software is expressly labeled to be for use on a multiuser or 
network system, or one copy of this software is purchased for each node or terminal on which Software is to be used simultaneously. 

D. CUSTOMER shall not use, make, manufacture, or reproduce copies of Software except for use on one computer and as is specifically provided in 
this Software License. Customer is expressly prohibited from disassembling the Software. 

E. CUSTOMER is permitted to make additional copies of the Software only for backup or archival purposes or if additional copies are required in the 
operation of one computer with the Software, but only to the extent the Software allows a backup copy to be made. However, for TRSDOS Software, 
CUSTOMER is permitted to make a limited number of additional copies for CUSTOMER’S own use. 

F. CUSTOMER may resell or distribute unmodified copies of the Software provided CUSTOMER has purchased one copy of the Software for each one 
sold or distributed. The provisions of this Software License shall also be applicable to third parties receiving copies of the Software from 
CUSTOMER. 

G. All copyright notices shall be retained on all copies of the Software. 


APPLICABILITY OF WARRANTY 


A. The terms and conditions of this Warranty are applicable as between RADIO SHACK and CUSTOMER to either a sale of the Equipment and/or 
Software License to CUSTOMER or to a transaction whereby Radio Shack sells or conveys such Equipment to a third party for lease to CUSTOMER. 

B. The limitations of liability and Warranty provisions herein shall inure to the benefit of RADIO SHACK, the author, owner and or licensor of the 
Software and any manufacturer of the Equipment sold by Radio Shack. 


STATE LAW RIGHTS 


The warranties granted herein give the original CUSTOMER specific legal rights, and the original CUSTOMER may have other rights which vary from 
state to state. : 
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Information in this document is subject to change without notice and does not represent a com- 
mitment on the part of The Santa Cruz Operation, Inc. nor Microsoft Corporation. The software 
described in this document is furnished under a license agreement or nondisclosure agreement. 
The software may be used or copied only in accordance with the terms of the agreement. It is 
against the law to copy this software on magnetic tape, disk, or any other medium for any purpose 
other than the purchaser’s personal use. 


© 1983, 1984 Microsoft Corporation 
© 1984, 1985 The Santa Cruz Operation, Inc. 
Licensed to Tandy Corporation 


XENIX is a registered trademark of Microsoft Corporation. 


Document Number: G-2-14-85-1.3/1.0 
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1.1 Overview 1 
1.2 Using the C Library Functions 1 
1.3 Using This Manual 1 


1.4 Notational Conventions 2 


1.1 Overview 


This manual explains how to use the functions given in the C language libraries of the XENIX 
system. In particular, it describes the functions of two C language libraries: the standard C 
library and the screen updating and cursor movement library curses. 


The C library functions may be called by any program that needs the resources of the XENIX 
system to perform a task. The functions let programs read and write to files in the XENIX file 
system, read and write to devices such as terminals and lineprinters, load and execute other 
programs, receive and process signals, communicate with other programs through pipes, share 
system resources, and process errors. 


1.2 Using the C Library Functions 


To use the C library functions you must include the proper function call and definitions in the 
program and make sure the corresponding library is given when the program is compiled. The 
standard C library, contained in the file /ibc.a, is automatically given when you compile a C 
language program. Other libraries, including the screen updating and cursor movement library 
contained in the file Jibcurses.a, must be explicitly given when you compile a program using the 
—I option of the ce command (see Chapter 2, “Cc: a C Compiler” in the XENIX Programmer's 
Guide). 


1.3 Using This Manual 


This manual is intended to be used in conjunction with section S of XENIX Reference Manual. If 
you have never used the C library functions before read this manual first, then refer to the 
Reference Manual to learn about other functions. If you are familiar with the library functions, 
turn to the Reference Manual to see how these functions may differ from the ones you already 
know, then return to this manual for examples of the functions. 


Chapter 1 introduces the C language libraries. 


Chapter 2 describes the standard input and output functions. These function let a program read 
and write to the files of a XENIX file system. 


Chapter 3 describes the screen processing functions. These functions let a program use the 
screen processing facilities of a user’s terminal. 


Chapter 4 describes the character and string processing functions. These functions let a program 
assign, manipulate, and compare characters and strings. 


Chapter 5 describes the process control functions. These functions let a program execute other 
programs and create multiple copies of itself. 


Chapter 6 describes the pipe functions. These functions let programs communicate with one 
another without resorting to the creation of temporary files. 


Chapter 7 describes the signal functions. These functions let a program processs the interrupt, 
quit, hangup, and other signals normally processed by the system. 


Chapter 8 describes system resource functions. These functions let a program dynamically 
allocate memory, share memory with other programs, lock files against access by other programs, 
and use semaphores. 


Chapter 9 describes the error processing functions. These functions let a program process errors 
encountered while accessing the file system or allocating memory. 


Appendix A describes the assembly language interface with C programs and explains the calling 
and return value conventions of C functions. 
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Appendix B explains how to create and use new XENIX system calls. 


This manual assumes that you understand the C programming language and that you are 
familiar with the XENIX shell, sh. Nearly all programming examples in this guide are written in 
C, and all examples showing a shell use the sh shell. 


1.4 Notational Conventions 


This manual uses a number of special symbols to describe the form of the library function calls. 
The following is a list of these symbols and their meaning. 


[ ] Brackets indicate an optional function argument. 
Ellipses indicate that the preceding argument may be repeated one or more times. 
SMALL Small capitals indicate manifest constants. 


italics Italic characters indicate placeholders for function arguments. These must be 
replaced with appropriate values or names of variables. 
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2.1 Introduction 


Nearly all programs use some form of input and output. Some programs read from or write to 
files stored on disk. Others write to devices such as line printers. Many programs read from and 
write to the user’s terminal. For this reason, the standard C library provides several predefined 
input and output functions that a programmer can use in programs. 


This chapter explains how to use the I/O functions in the standard C library. In particular, it 
describes: 


— Command line arguments 

— Standard input and output files 

— Stream functions for ordinary files 
— Low-level functions for ordinary files 


— Random access functions 
2.1.1 Preparing for the I/O Functions 


To use the standard I/O functions a program must include the file stdio.h, which defines the 
needed macros and variables. To include this file, place the following line at the beginning of the 
program. 


#include <stdio.h> 


The actual functions are contained in the library file /ibc.a. This file is automatically read 
whenever you compile a program, so no special argument is needed when you invoke the 
compiler. 


2.1.2 Special Names 


The standard I/O library uses many names for special purposes. In general, these names can be 
used in any program that has included the stdio.h file. The following is a list of the special names: 


stdin The name of the standard input file. 


stdout The name of the standard output file. 


stderr The name of the standard error file. 

EOF The value returned by the read routines on end-of-file or error. 

NULL The null pointer, returned by pointer-valued functions, to indicate an error. 
FILE The name of the file type used to declare pointers to streams. 


BSIZE The size in bytes (usually 1024) suitable for an I/O buffer supplied by the user. 


2.1.3 Special Macros 


The functions getc, getchar, putc, putchar, feof, ferror, and fileno are actually macros, not 
functions. This means that you cannot redeclare them or use them as targets for a breakpoint 
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when debugging. 
2.2 Using Command Line Arguments 


The XENIX system lets you pass information to a program at the same time you invoke it for 
execution. You can do this with command line arguments. 


A XENIX command line is the line you type to invoke a program. A command line argument is 
anything you type in a XENIX command line. A command line argument can be a filename, an 
option, or a number. The first argument in any command line must be the filename of the 
program you wish to execute. 


When you type a command line, the system reads the first argument and loads the corresponding 
program. It also counts the other arguments, stores them in memory in the same order in which 
they appear on the line, and passes the count and the locations to the main function of the 
program. The function can then access the arguments by accessing the memory in which they are 
stored. 


To access the arguments, the main function must have two parameters: “‘arge’’, an integer 
variable containing the argument count, and “argv’’, an array of pointers to the argument values. 
You can define the parameters by using the lines: 


main (argc, argv) 
int argc; 
char *argv[]; 


at the beginning of the main program function. When a program begins execution, “argc” 
contains the count, and each element in “argv” contains a pointer to one argument. 


An argument is stored as a null-terminated string (i.e., a string ending with a null character, \0). 
The first string (at “‘argv[0]’’) is the program name. The argument count is never less than 1, 
since the program name is always considered the first argument. 


In the following example, command line arguments are read and then echoed on the terminal 
screen. This program is similar to the XENIX echo command. 


main(argc, argv) /* echo arguments */ 
int argc; 

char *argv[]; 

{ 


int 1; 


fori 131 << argop i++) 
printf("%s%c", argv[i], (i<arge—1) ?’’:’\n’); 


In the example above, an extra space character is added at the end of each argument to separate it 
from the next argument. This is required, since the system automatically removes leading and 
trailing whitespace characters (i.e., spaces and tabs) when it reads the arguments from the 
command line. Adding a newline character to the last argument is for convenience only; it causes 
the shell prompt to appear on the next line after the program terminates. 


When typing arguments on a command line, make sure each argument is separated from the 
others by one or more whitespace characters. If an argument must contain whitespace 
characters, enclose that argument in double quotation marks. For example, in the command line 


display 3 4 "echo hello" 


the string “‘echo hello” is treated as a single argument Also enclose in double quotation marks any 
argument that contains characters recognized by the shell (e.g., <, >,| and “*). 
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You should not change the values of the “argc” and “‘argv” variables. If necessary, assign the 
argument value to another variable and change that variable instead. You can give other 
functions in the program access to the arguments by assigning their values to external variables. 


2.3 Using the Standard Files 


Whenever you invoke a program for execution, the XKENIX system automatically creates a 
standard input, a standard output, and a standard error file to handle a program’s input and 
output needs. Since the bulk of input and output of most programs is through the user’s own 
terminal, the system normally assigns the user’s terminal keyboard and screen as the standard 
input and output, respectively. The standard error file, which receives any error messages 
generated by the program, is also assigned to the terminal’s screen. 


A program can read and write to the standard input and output files with the getchar, gets, scanf, 
putchar, puts, and printf functions. The standard error file can be accessed using the stream 
functions described in the section “Using Stream I/O” later in this chapter. 


The XENIX system lets you redirect the standard input and output using the shell’s redirection 
symbols. This allows a program to use other devices and files as its chief source of input and 
output in place of the terminal’s keyboard and screen. 


The following sections explains how to read from and write to the standard input and output. It 
also explains how to redirect the standard input and output. 


2.3.1 Reading From the Standard Input 


You can read from the standard input with the getchar, gets, and scanf functions. 


The getchar function reads one character at a time from the standard input. The function call 
has the form: | 


c = getchar() 


where c is the variable to receive the character. It must have int type. The function normally 
returns the character read, but will return the end-of-file value EOF if the end of the file or an 
error is encountered. 


The getchar function is typically used in a conditional loop to read a string of characters from the 
standard input. For example, the following function reads “‘cnt” number of characters from the 
keyboard. 


readn (p, cnt) 
char p[]; 

int cnt; 

{ 


ifit. 1,¢: 


i = 0; 
while ( i<cnt ) 
if ((p[it+] = getchar()) == EOF ) { 
pli] = 0; 
return(EOF); 
} 


return(0); 


j 


Note that if getchar is reading from the keyboard, it waits for characters to be typed before 
returning. 
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The gets function reads a string of characters from the standard input and copies the string toa 
given memory location. The function call has the form: 


gets(s) 


where s is a pointer to the location to receive the string. The function reads characters until it 
finds a newline character, then replaces the newline character with a null character (\0) and 
copies the resulting string to memory. The function returns the null pointer value NULL if the 
end of the file or an error is encountered. Otherwise, it returns the value of s. 


The function is typically used to read a full line from the standard input. For example, the 
following program fragment reads a line from the standard input, stores it in the character array 
““cmdIn” and calls a function (called parse) if no error occurs. 


char cmdln[SIZE]; 


if ( gets(cmdln) != NULL ) 
parse(); 


In this case, the length of the string is assumed to be less than “SIZE”. 
Note that gets cannot check the length of the string it reads, so overflow can occur. 


The scanf function reads one or more values from the standard input where a value may be a 
character string or a decimal, octal, or hexadecimal number. The function call has the form: 


scanf (format, argptr ...) 


where format is a pointer to a string that defines the format of the values to be read and argptr is 
one or more pointers to the variables that will receive the values. There must be one argptr for 
each format given in the format string. The format may be “%s” for a string, “%c’’ for a 
character, and “%d”’, “%o’’, or “%x”’ for a decimal, octal, or hexadecimal number, respectively. 
(Other formats are described in scanf(S) in the XENIX Reference Manual.) The function 
normally returns the number of values it read from the standard input, but it will return the value 
EOF if the end of the file or an error is encountered. 


Unlike the getchar and gets functions, scanf skips all whitespace characters, reading only those 
characters which make up a value. It then converts the characters, if necessary, into the 
appropriate string or number. 


The scanf function is typically used whenever formatted input is required, i.e., input that must be 
typed in a special way or which has a special meaning. For example, in the following program 
fragment scanf reads both a name and a number from the same line. 


char name[20]; 
int number; 
scanf("%s %d", name, &number); 


In this example, the string “%s %d”’ defines what values are to be read (a string and a decimal 
number). The string is copied to the character array “name” and the number to the integer 
variable “number’’. Note that pointers to these variables are used in the call and not the actual 
variables themselves. 


When reading from the keyboard, scanf waits for values to be typed before returning. Each value 
must be separated from the next by one or more whitespace characters (such as spaces, tabs, or 
even newline characters). For example, for the function: 


scanf("%s Y%d %c", name, age, sex); 
an acceptable input is: 


John 27 
M 
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If a value is a number, it must have the appropriate digits, that is, a decimal number must have 
decimal digits, octal numbers octal digits, and hexadecimal numbers hexadecimal digits. 


If scanf encounters an error, it immediately stops reading the standard input. Before scanf can 
be used again, the illegal character that caused the error must be removed from the input using 
the getchar function. 


You may use the getchar, gets, and scanf functions ina single program. Just remember that each 
function reads the next available character, making that character unavailable to the other 
functions. 


Note that when the standard input is the terminal keyboard, the getchar, gets, and scanf 
functions usually do not return a value until at least one newline character has been typed. This is 
true even if only one character is desired. 


2.3.2 Writing to the Standard Output 


You can write to the standard output with the putchar, puts, and printf functions. 


The putchar function writes a single character to the output buffer. The function call has the 
form: 


putchar (c) 


where c is the character to be written. The function normally returns the same character it wrote, 
but will return the value EOF if an error is encountered. 


The function is typically used in a conditional loop to write a string of characters to the standard 
output. For example, the function 


writen (p,cnt) 
char p[]; 

int cnt; 

{ 


mee 


for (i=0; i<=cnt; i++) 
putchar( (i != cnt) ? p[i] : \n’); 
} 


writes “cnt” number of characters plus a newline character to the standard output. 


The puts function copies the string found at a given memory location to the standard output. The 
function call has the form: 


puts(s) 


where s is a pointer to the location containing the string. The string may be any number of 
characters, but must end with a null character (\0). The function writes each character in the 
string to the standard output and replaces the null character at the end of the string with a 
newline character. 


Since the function automatically appends a newline character, it is typically used when writing 
full lines to the standard output. For example, the following program fragment writes one of 
three strings to the standard output. 
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char ic: 


switch(c) { 

case(’1’): 
puts("Continuing..."); 
break; 

case(’2’): 
puts("All done."); 
break; 

default: 
puts("Sorry, there was an error."); 


j 
The string to be written depends on the value of “‘c’”’. 


The printf function writes one or more values to the standard output where a value is a character 
string or a decimal, octal, or hexadecimal number. The function automatically converts numbers 
into the proper display format. The function call has the form: 


printf(format[, arg] ...) 


where format is a pointer to a string which describes the format of each value to be written and 
arg is one or more variables containing the values to be written. There must be one arg for each 
format in the format string. The formats may be ““%s”’ for a string, ““%c”’ for a character, and 
“Zod”, ““%oo”’, or “%x”’ for a decimal, octal, or hexadecimal number, respectively. (Other formats 
are described in printf(S) in the XENIX Reference Manual.) If a string is requested, the 
corresponding arg must be a pointer. The function normally returns zero, but will return a 
nonzero value if an error is encountered. 


The printf function is typically used when formatted output is required, i.e., when the output 
must be displayed in a certain way. For example, you may use the function to display a name and 
number on the same line as in the following example. 


char name []; 
int number; 


printf("%s %d", name, number); 


In this example, the string “%s %d”’ defines the type of output to be displayed (a string and a 
number separated by a space). The output values are copied from the character array “name” 
and the integer variable “number’”’. 


You may use the putchar, puts, and printf functions in a single program. Just remember that the 
output appears in the same order as it is written to the standard output. 


2.3.3 Redirecting the Standard Input 


You can change the standard input from the terminal keyboard to an ordinary file by using the 
normal shell redirection symbol, <. This symbol directs the shell to open for reading the file 
whose name immediately follows the symbol. For example, the following command line opens 
the file phonelist as the standard input to the program dial. 


dial <phonelist 


The dial program may then use the getchar, gets, and scanf functions to read characters and 
values from this file. Note that if the file does not exist, the shell displays an error message and 
does not execute the program. 


Whenever getchar, gets, or scanf are used to read from an ordinary file, they return the value 
EOF if the end of the file or an error is encountered. It is useful to check for this value to make 
sure you do not continue to read characters after an error has occurred. 
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2.3.4 Redirecting the Standard Output 


You can change the standard output of a program from the terminal screen to an ordinary file by 
using the shell redirection symbol, >. The symbol directs the shell to open for writing the file 
whose name immediately follows the symbol. For example, the command line 


dial >savephone 


opens the file savephone as the standard output of the program dial and not the terminal screen. 
You may use the putchar, puts, and printf functions to write to the file. 


If the file does not exist, the shell automatically creates it. If the file exists, but you do not have 
permission to change or alter the file, the shell displays an error message and does not execute the 
program. 


2.3.5 Piping the Standard Input and Output 


Another way to redefine the standard input and output is to create a pipe. A pipe simply connects 
the standard output of one program to the standard input of another. The programs may then use 
the standard input and output to pass information from one to the other. You can create a pipe by 
using the standard shell pipe symbol, | 


For example, the command line 

dial | we 
connects the standard output of the program dial to the standard input of the program we. (The 
standard input of dial and standard output of wc are not affected.) If dial writes to its standard 


output with the putchar, puts, or printf functions, wc can read this output with the getchar and 
scanf functions. 


Note that when the program on the output side of a pipe terminates, the system automatically 
places the constant value EOF in the standard input of the program on the input side. Pipes are 
described in more detail in Chapter 6, “Creating and Using Pipes”’. 


2.3.6 Program Example 


This section shows how you may use the standard input and output files to perform useful tasks. 
The ccstrip (for “control character strip’’) program defined below strips out all ASCII control 
characters from its input except for newline and tab. You may use this program to display text or 
data files which contain characters that may disrupt your terminal screen. 


#include <stdio.h> 
main() /* ccstrip: strip control characters */ 


init? 
while ((c = getchar()) != EOF) 
if ((c >=’ && c < 0177) | 
c ==\t?|c == ’\n) 
putchar(c); 
exit(0); 
} 


You can strip and display the contents of a single file by changing the standard input of the 
ccstrip program to the desired file. The command line 


cestrip <doc.t 
reads the contents of the file doc.t, strips out control characters, then writes the stripped file to the 
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standard output. 


If you wish to strip several files at the same time, you can create a pipe between the cat command 
and ccstrip. 


To read and strip the contents of the files file] , file2, and file3, then display them on the standard 
output use the command: 


cat filel file2 file3 | ccstrip 


If you wish to save the stripped files, you can redirect the standard output of ccstrip. For 
example, this command line writes the stripped files to the file clean. 


cat filel file2 file3 | ccstrip >clean 


Note that the exit function is used at the end of the program to ensure that any program which 
executes the ccstrip program will receive a normal termination status (typically 0) from the 
program when it completes. An explanation of the exit function and how to execute one program 
under control of another is given in Chapter 5. 


2.4 Using the Stream Functions 


The functions described so far have all read from the standard input and written to the standard 
output. The next step is to show functions that access files not already connected to the program. 
One set of standard I/O functions allows a program to open and access ordinary files as if they 
were a “stream” of characters. For this reason, the functions are called the stream functions. 


Unlike the standard input and output files, a file to be accessed by a stream function must be 
explicitly opened with the fopen function. The function can open a file for reading, writing, or 
appending. A program can read from a file with the getc, fgetc, fgets, fgetw, fread, and fscanf 
functions. It can write toa file with the putc, fputc, fputs, fputw, fwrite, and fprintf functions. A 
program can test for the end of the file or for an error with the feof and ferror functions. A 
program can close a file with the fclose function. 


2.4.1 Using File Pointers 


Every file opened for access by the stream functions has a unique pointer associated with it called 
a file pointer. This pointer, defined with the predefined type FILE found in the stdio.h file, points 
to a structure that contains information about the file, such as the location of the buffer (the 
intermediate storage area between the actual file and the program), the current character 
position in the buffer, and whether the file is being read or written. The pointer can be given a 
valid pointer value with the fopen function as described in the next section. (The NULL value, 
like FILE, is defined in the stdio.h file. ) Thereafter, the file pointer may be used to refer to that file 
until the file is explicitly closed with the fclose function. 


Typically, a file pointer is defined with the statement: 
FILE *infile; 


The standard input, output, and error files, like other opened files, have corresponding file 
pointers. These file pointers are named stdin for standard input, stdout for standard output, and 
stderr for standard error. Unlike other file pointers, the standard file pointers are predefined in 
the stdio.h file. This means a program may use these pointers to read and write from the standard 
files without first using the fopen function to open them. 


The predefined file pointers are typically used when a program needs to alternate between the 
standard input or output file and an ordinary file. Although the predefined file pointers have FILE 
type, they are constants, not variables. They must not be assigned values. 
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2.4.2 Opening a File 


The fopen function opens a given file and returns a pointer (called a file pointer) to a structure 
containing the data necessary to access the file. The pointer may then be used in subsequent 
stream functions to read from or write to the file. 


The function call has the form: 


Sp = fopen(filename, type) 
where fp is the pointer to receive the file pointer, filename is a pointer to the name of the file to be 
opened and type is a pointer to a string that defines how the file is to be opened. The type string 


may be “‘r” for reading, “w” for writing, and “‘a” for appending, that is, open for writing at the 
end of the file. 


A file may be opened for different operations at the same time if separate file pointers are used. 
For example, the following program fragment opens the file named /usr/accounts for both 
reading and writing. 


FILE *rp, *wp; 
rp = fopen("/usr/accounts","r"); 
wp = fopen("/usr/accounts","a"); 


Opening an existing file for writing destroys the old contents. Opening an existing file for 
appending leaves the old contents unchanged and causes any data written to the file to be 
appended to the end. 


Trying to open a nonexistent file for reading causes an error. Trying to open a nonexistent file for 
writing or appending causes a new file to be created. Trying to open any file for which the 
program does not have appropriate permission Causes an error. 


The function normally returns a valid file pointer, but will return the value NULL if an error 
opening the file is encountered. It is wise to check for the NULL value after each call to the 
function to prevent reading or writing after an error. 


2.4.3 Reading a Single Character 


The getc and fgetc functions return a single character read from a given file, and return the value 
EOF if the end of the file or an error is encountered. The function calls have the form: 


c = getc (stream) 
and 
c = fgetc (stream) 


where stream is the file pointer to the file to be read and c is the variable to receive the character. 
The return value is always an integer. 


The functions are typically used in conditional loops to read a string of characters from a file. For 
example, the following program fragment continues to read characters from the file given to it by 
“‘infile” until the end of the file or an error is encountered. 

int 1; 

char buf[MAX]; 

FILE *infile; 


while ((c=getc(infile)) != EOF) 
buf[i++]=c; 
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The only difference between the functions is that getc is defined as a macro, and fgetc as a true 
function. This means that, unlike getc, fgetc may be passed as an argument in another function, 
used as a target for a breakpoint when debugging, or used to avoid any side effects of macro 
processing. 


2.4.4 Reading a String from a File 


The fgets function reads a string of characters a file and copies the string to a given memory 
location. The function call has the form: 


fgets (s,n,stream) 


where s is be a pointer to the location to receive the string, nis a count of the maximum number of 
characters to be in the string, and stream is the file pointer of the file to be read. The function 
reads n—/ characters or upto to the first newline character, whichever occurs first. The function 
appends a null character (\0) to the last character read and then stores the string at the specified 
location. The function returns the null pointer value NULL if the end of the file or an error is 
encountered. Otherwise, it returns the pointer s. 


The function is typically used to read a full line from a file. For example, the following program 
fragment reads a string of characters from the file given by “myfile’’. 


char cmdln[MAX]; 
FILE *myfile; 


if ( fgets( cmdln, MAX, myfile ) != NULL) 
parse( cmdln ); 


In this example, fgets copies the string to the character array “cmdlIn”’. 


2.4.5 Reading Records from a File 


The fread function reads one or more records from a file and copies them to a given memory 
location. The function call has the form: 


fread(ptr, size, nitems, stream) 


where ptr is a pointer to the location to receive the records, size is the size (in bytes) of each record 
to be read, nitems is the number of records to be read, and stream is the file pointer of the file to be 
read. The ptr may bea pointer to a variable of any type (from a single character to a structrure). 
The size, an integer, should give the numbers of bytes in each item you wish to read. One way to 
ensure this is to use the sizeof function on the pointer ptr (see the example below). The function 
always returns the number of records it read, regardless of whether or not the end of the file or an 
error is encountered. 


The function is typically used to read binary data froma file. For example, the following program 
fragment reads two records from the file given by “database” and copies the records into the 
structure “person”’. 


FILE *database; 

struct record { 
char name[20]; 
int age; 

} person[2]; 


fread( &person, sizeof(struct record), 2, database); 


Note that since fread does not explicitly indicate errors, the feof and ferror functions should be 
used to detect end of the file and errors. These functions are described later in this chapter. 
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2.4.6 Reading Formatted Data From a File 


The fscanf function reads formatted input from a given file and copies it to the memory location 
given by the respective argument pointers, just as the scanf function reads from the standard 
input. The function call has the form: 


fscanf (stream, format, argptr ...) 


where stream is the file pointer of the file to be read, format is a pointer to the string that defines 
the format of the input to be read, and argptr is one or more pointers to the variables that are to 
receive the formatted input. There must be one argptr for each format given in the format string. 
The format may be “%s” for a string, “%c” for a character, and “%d”’, “%o”’, or “%x”’ for a 
decimal, octal, or hexadecimal number, respectively. (Other formats are described in scanf(S) in 
the XENIX Reference Manual.) The function normally returns the number of arguments it read, 
but will return the value EOF if the end of the file or an error is encountered. 


The function is typically used to read files that contain both numbers and text. For example, this 
program fragment reads a name and a decimal number from the file given by “file”. 


FILE *file; 


int pay; 
char name[20]; 


fscanf(file,"%s %d\n", name, &pay); 


This program fragment copies the name to the character array “name” and the number to the 
integer variable “pay’”’. 


2.4.7 Writing a Single Character 


The putc and fputc functions write single characters to a given file. The function calls have the 
forms: 


putc (c,stream) 
and 
fputc (c,stream) 


where c is the character to be written and stream is the file pointer to the file to receive the 
character. The function normally returns the character written, but will return the value EOF if 
an error is encountered. 


The putc function is defined as a macro and may have undesirable side effects resulting from 
argument processing. In such cases, the equivalent function fputc should be used. 


These functions are typically used in conditional loops to write a string of characters toa file. For 
example, this following program fragment writes characters from the array “name” to the file 
given by “out”’. 

FILE *out; 


char name[MAX]; 
int 1; 


for (i=0; i<MAX; i++) 
fputc( name[i], out); 


The only difference between the putc and fputc functions is that putc is defined as a macro and 
fputc as an actual function. This means that fputc, unlike putc, may be used as an argument to 
another function, as the target of a breakpoint when debugging, and to avoid the side effects of 
macro processing. 
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2.4.8 Writing a String to a File 


The fputs function writes a string to a given file. The function call has the form: 
fputs(s,stream) 
where s is a pointer to the string to be written and stream is the file pointer to the file. 


The function is typically used to copy strings from one file to another. For example, in the 
following program fragment, gets and fputs are combined to copy strings from the standard input 
to the file given by “‘out”’. 


FILE *out; 
char cmdIn[MAX]; 


if ( gets( cmdln ) != EOF ) 
fputs( cmdln, out); 


The function normally returns zero, but will return EOF if an error is encountered. 
2.4.9 Writing Formatted Output 


The fprintf function writes formatted output to a given file, just as the printf function writes to 
the standard output. The function call has the form: 


fprintf (stream, format [, arg ]...) 


where stream is the file pointer of the file to be written to, format is a pointer to a string which 
defines the format of the output, and arg is one or more arguments to be written. There must be 
one arg for each format in the format string. The formats may be ““%s” for a string, “%c” for a 
character, and “%d”’, “%o’’, or ““%x” for a decimal, octal, or hexadecimal number, respectively. 
(Other formats are described in printf(S) in the XENIX Reference Manual.) If a string is 
requested, the corresponding arg must be a pointer, otherwise, the actual variable must be used. 
The function normally returns zero, but will return a nonzero number if an error is encountered. 


The function is typically used to write output that contains both numbers and text. For example, 
to write a name and a decimal number to the file given by “‘outfile” use the following program 
fragment. 


FILE *outfile; 
int pay; 
char name[20]; 


fprintf(outfile,"%s %d\n", name, pay); 


The name is copied from the character array “name” and the number from the integer variable 


66 99 


pay . 
2.4.10 Writing Records to a File 


The fwrite function writes one or more records toa given file. The function call has the form: 
fwrite (ptr, size, nitems, stream) 


where ptr is a pointer to the first record to be written, size is the size (in bytes) of each record, 
nitems is the number of records to be written, and stream is the file pointer of the file. The ptr 
may point to a variable of any type (from a single character to a structure). The size should give 
the number of bytes in each item to be written. One way to ensure this is to use the sizeof function 
(see the example below). The function always returns the number of items actually written to the 
file whether or not the end of the file or an error is encountered. 
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The function is typically used to write binary data toa file. For example, the following program 
fragment writes two records to the file given by “database”. 


FILE *database; 
struct record { 
char name[20]; 
int age; 
} person[2]; 
fwrite(&person, sizeof(struct record), 2, database); 


The records are copied from the structure “person’”’. 


Since the function does not report the end of the file or errors, the feof and ferror functions should 
be used to detect these conditions. 


2.4.11 Testing for the End of a File 


The feof function returns the value —1 if a given file has reached its end. The function call has the 
form: 


feof (stream) 


where stream is the file pointer of the file. The function returns —1 only if the file has reached its 
end, otherwise it returns 0. The return value is always an integer. 


The feof function is typically used after those functions whose return value is not a clear indicator 
of an end-of-file condition. For example, in the following program fragment the function checks 
for the end of the file after each character is read. The reading stops as soon as feof returns —1. 


char name[10]; 
FILE *stream; 


do 
fread( name, sizeof(name), 1, stream ); 
while(!feof( stream )); 


2.4.12 Testing For File Errors 


The ferror function tests a given stream file for an error. The function call has the form: 
ferror (stream) 


where stream is the file pointer of the file to be tested. The function returns a nonzero (true) value 
if an error is detected, otherwise it returns zero (false). The function returns an integer value. 


The function is typically used to test for errors before perform a subsequent read or write to the 
file. For example, in the following program fragment ferror tests the file given by “stream”. 


char buf[5]; 
FILE *stream; 
while ( !ferror(stream) ) 
fread(buf, sizeof(x), 1, stream); 


If it returns zero, the next item in the file given by “stream” is copied to “buf”. Otherwise, 
execution passes to the next statement. 


Further use of a file after a error is detected may cause undesirable results. 
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2.4.13 Closing a File 


The fclose function closes a file by breaking the connection between the file pointer and the 
structure created by fopen. Closing a file empties the contents of the corresponding buffer and 
frees the file pointer for use by another file. The function call has the form: 


fclose (stream) 


where stream is the file pointer of the file to close. The function normally returns 0, but will 
return —1 if anerror is encountered. 


The fclose function is typically used to free file pointers when they are no longer needed. This is 
important because usually no more than 20 files can be open at the same time. For example, the 
following program fragment closes the file given by “‘infile” if the file has reached its end. 


FILE *infile; 


if ( feof(infile) ) 
fclose( infile ); 


Note that whenever a program terminates normally, the fclose function is automatically called 
for each open file, so no explicit call is required unless the program must close a file before its end. 
Also, the function automatically calls flush to ensure that everything written to the file’s buffer 
actually gets to the file. 


2.4.14 Program Example 


This section shows how you may use the stream functions you have seen so far to perform useful 
tasks. The following program, which counts the characters, words, and lines found in one or more 
files, uses the fopen, fprintf, getc, and fclose functions to open, close, read, and write to the given 
files. The program incorporates a basic design that is common to other XENIX programs, namely 
it uses the filenames found in the command line as the files to open and read, or if no names are 
present, it uses the standard input. This allows the program to be invoked on its own, or be the 
receiving end of a pipe. 
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#include <stdio.h> 


main(arge, argv) /* wc: count lines, words, chars */ 


int argc; 


char *argv[]; 


} 


int c, i, inword; 

FILE *fp, *fopen(); 

long linect, wordct, charct; 

long tlinect = 0, twordct = 0, tcharct = 0; 


i=1; 
fp = stdin; 
do 
{ 
if (argc > 1 && 
(fp=fopen(argv[i], "r")) == NULL) { 
fprintf (stderr, "we: can’t open %s\n", 
argv(i}); 
continue; 
} 
linect = wordct = charct = inword = 0; 
while ((c = getc(fp)) != EOF) { 


charct++; 
if (c == ’\n’) 
linect++; 
if (c ==’? |c ==\t? |c == ’\n’) 
inword = 0; 
else if (inword == 0) { 
inword = 1; 
wordct++; 
} 


} 
printf("%71d %7ld %71d", linect, wordct, charct); 
printf(arge > 1?" %s\n": "\n", argv[i]); 
fclose(fp); 
tlinect += linect; 
twordct += wordct; 
tcharct += charct; 
} while (++i < argc); 
if (argc > 2) 
printf("%71ld %7ld %7ld total\n", tlinect, 
twordct, tcharct); 
exit(0); 


The program uses “fp” as the pointer to receive the current file pointer. Initially this is set to 
“stdin” in case no filenames are present in the command line. If a filename is present, the 
program calls fopen and assigns the file pointer to “fp”. If the file cannot be opened (in which 
case fopen returns NULL), the program writes an error message to the standard error file 
“stderr” with the fprintf function. The function prints the format string “wc: can’t open %s”’, 
replacing the “%s” with the name pointed to by “argv[i]”’. 


Once a file is opened, the program uses the getc function to read each character from the file. As 
it reads characters, the program keeps a count of the number of characters, words, and lines. The 
program continues to read until the end of the file is encountered, that is, when getc returns the 


value EOF. 
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Once a file has reached its end, the program uses the printf function to display the character, 
word, and line counts at the standard output. The format string in this function causes the counts 
to be displayed as long decimal numbers with no more than 7 digits. The program then closes the 
current file with the fclose function and examines the command line arguments to see if there is 
another filename. 


When all files have been counted, the program uses the printf function to display a grand total at 
the standard output, then stops execution with the exit function. 


2.5 Using More Stream Functions 


The stream functions allow more control over a file than just opening, reading, writing, and 
closing. The functions also let a program take an existing file pointer and reassign it to another 
file (similar to redirecting the standard input and output files) as well as manipulate the buffer 
that is used for intermediate storage between the file and the program. 


2.5.1 Using Buffered Input and Output 


Buffered I/O is an input and output technique used by the XENIX system to cut down the time 
needed to read from and write to files. Buffered I/O lets the system collect the characters to be 
read or written and then transfer them all at once rather than one character at a time. This 
reduces the number of times the system must access the I/O devices and consequently provides 
more time for running user programs. Not all files have buffers. For example, files associated 
with terminals, such as the standard input and output, are not buffered. This prevents unwanted 
delays when transferring the input and output. When a file does have a buffer, the buffer size in 
bytes is given by the manifest constant BUFSIZ, which is defined in the stdio.h file. 


When a file has a buffer, the stream functions read from and write to the buffer instead of the file. 
The system keeps track of the buffer and when necessary fills it with new characters (when 
reading) or flushes (copies) it to the file (when writing). Normally, a buffer is not directly 
accessible to a program, however a program can define its own buffer for a file with the setbuf 
function. The function also lets a program change a buffered file to be an unbuffered one. The 
ungetc function lets a program put a character it has read back into the buffer, and the flush 
function lets a program flush the buffer before it is full. 


2.5.2 Reopening a File 


The freopen closes the file associated with a given file pointer, then opens a new file and gives it 
the same file pointer as the old file. The function call has the form: 


freopen (newfile, type, stream) 


where new/ile is a pointer to the name of the new file, type is a pointer to the string that defines 
how the file is to be opened (“r” for read, “w” for writing, and “a” for appending), and stream is 
the file pointer of the old file. The function returns the file pointer stream if the new file is opened. 
Otherwise, it returns the null pointer value NULL. 


The freopen function is used chiefly to attach the predefined file pointers “stdin’’, “stdout”, and 
“stderr” to other files. For example, the following program fragment opens the file named by 
““newfile” as the new standard output file. 


char *newfile; 
FILE *nfile; 


nfile = freopen(newfile,"w",stdout); 


This has the same effect as using the redirection symbols in the command line of the program. 
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2.5.3 Setting the Buffer 


The setbuf function changes the buffer associated with a given file to the program’s own buffer. It 
can also change the access to the file to no buffering. The function call has the form: 


setbuf (stream, buf) 


where stream is a file descriptor and buf is a pointer to the new buffer, or is the null pointer value 
NULL if no buffering is desired. If a buffer is given, it must be BUFSIZ bytes in length, where 
BUFSIZ is a manifest constant found in stdio.h. 


The function is typically used to to create a buffer for the standard output when it is assigned to 
the user’s terminal, improving execution time by eliminating the need to write one character to 
the screen at a time. For example, the following program fragment changes the buffer of the 


66.99 


standard output the location pointed at by “p”’. 


char *p; 


p=malloc( BUFSIZ ); 
setbuf ( stdout, p ); 


The new buffer is BUFSIZ bytes long. 


The function may also be used to change a file from buffered to unbuffered input or output. 
Unbuffered input and output generally increase the total time needed to transfer large numbers 
of characters to or from a file, but give the fastest transfer speed for individual characters. 


The setbuf function should be called immediately after opening a file and before reading or 
writing to it. Furthermore, the fclose or ffiush function must be used to flush the buffer before 
terminating the program. If not used, some data written to the buffer may not be written to the 
file. 


2.5.4 Putting a Character Back into a Buffer 


The ungetc function puts a character back into the buffer of a given file. The function call has the 
form: 


ungetc (c, stream) 


where c is the character to put back and stream is the file pointer of the file. The function 
normally returns the same character it put back, but will return the value EOF if an error is 
encountered. 


The function is typically used when scanning a file for the first character of a string of characters. 
For example, the following program fragment puts the first character that is not a whitespace 
character back into the buffer of the file given by “‘infile’’, allowing the subsequent call to gets to 
read that character as the first character in the string. 


FILE *infile 
char name[20]; 


while( isspace( c=getc(infile) ) ) 


ungetc( c, stdin ); 
gets( name, stdin ); 


Putting a character back into the buffer does not change the corresponding file; it only changes 
the next character to be read. 


Note that the function can put a character back only if one has been previously read. The 
function cannot put more than one character back at a time. This means if three characters are 
read, then only the last character can be put back, never the first two. 
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Note that the value EOF must never be put back in the buffer. 


2.5.5 Flushing a File Buffer 


The fflush function empties the buffer of a give file by immediately writing the buffer contents to 
the file. The function call has the form: 


flush (stream) 


where stream is the file pointer of the file. The function normally returns zero, but will return the 
value EOF if an error is encountered. 


The function is typically used to guarantee that the contents of a partially filled buffer are written 
to the file. For example, the following program fragment empties the buffer for the file given by 
“outtty” if the error condition given by “errflag” is 0. 


FILE *outtty; 
int errflag; 


if (errflag == 0) 
flush( outtty ); 


Note that flush is automatically called by the fclose function to empty the buffer before closing 
the file. This means that no explicit call to flush is required if the file is also being closed. 


The function ignores any attempt to empty the buffer of a file opened for reading. 
2.6 Using the Low-Level Functions 


The low-level functions provide direct access to files and peripheral devices. They are actually 
direct calls to the routines used in the XENIX operating system to read from and write to files and 
peripheral devices. The low-level functions give a program the same control over a file or device 
as the system, letting it access the file or device in ways that the stream functions do not. 
However, low-level functions, unlike stream functions, do not provide buffering or any other 
useful services of the stream functions. This means that any program that uses the low-level 
functions has the complete burden of handling input and output. 


The low-level functions, like the stream functions, cannot be used to read from or write to a file 
until the file has been opened. A program may use the open function to open an existing or a new 
file. A file can be opened for reading, writing, or appending. 


Once a file is opened for reading, a program can read bytes from it with the read function. A 
program can write to a file opened for writing or appending with the write function. A program 
can close a file with the close function. 


2.6.1 Using File Descriptors 


Each file that has been opened for access by the low-level functions has a unique integer called a 
“file descriptor” associated with it. A file descriptor is similar to a file pointer in that it identifies 
the file. A file descriptor is unlike a file pointer in that it does not point to any specific structure. 
Instead the descriptor is used internally by the system to access the necessary information. Since 
the system maintains all information about a file, the only access toa file for a program is through 
the file descriptor. 


There are three predefined file descriptors (just as there are three predefined file pointers) for the 
standard input, output, and error files. The descriptors are 0 for the standard input, | for the 
standard output, and 2 for the standard error file. As with predefined file pointers, a program 
may use the predefined file descriptors without explicitly opening the associated files. 
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Note that if the standard input and output files are redirected, the system changes the default 
assignments for the file descriptors 0 and 1 to the named files. This is also true if the input or 
output is associated with a pipe. File descriptor 2 normally remains attached to the terminal. 


2.6.2 Opening a File 


The open function opens an existing or a new file and returns a file descriptor for that file. The 
function call has the form: 


fd = open(name, access |,mode] ); 


where fd is the integer variable to receive the file descriptor, name is a pointer to a string 
containing the filename, access is an integer expression giving the type of file access, and mode is 
an integer number giving a new file’s permissions. The function normally returns a file descriptor 
(a positive integer), but will return —1 if an error is encountered. 


The access expression is formed by using one or more of the following manifest constants: 
O RDONLY for reading, O WRONLY for writing, O RDWR for both reading and writing, 
O APPEND for appending to the end of an existing file, and O CREAT for creating a new file. 
(Other constants are described in open(S) in the XENIX Reference Manual.) The logical OR 
operator (|) may be used to combine the constants. The mode is required only if O CREAT is 
given. For example, in the following program fragment, the function is used to open the existing 
file named /usr/accounts for reading and open the new file named /usr/tmp/scratch for reading 
and writing. 


int in, out; 


in = open( "/usr/accounts", O RDONLY ); 
out = open( "/usr/tmp/scratch", O RDWR |O_CREAT, 0754 ); 


In the XENIX system, each file has 9 bits of protection information which control read, write, and 
execute permission for the owner of the file, for the owner’s group, and for all others. A three- 
digit octal number is the most convenient way to specify the permissions. For example, in the 
example above the octal number “0755” specifies read, write, and execute permission for the 
owner, read and execute permission for the group, and read everyone else. 


Note that if O CREAT is given and the file already exists, the function destroys the file’s old 
contents. 


2.6.3 Reading Bytes From a File 


The read function reads one or more bytes of data from a given file and copies them to a given 
memory location. The function call has the form: 


n_read = read(fd, buf, n); 


where n_read is the variable to receive the count of bytes actually read, fd is the file descriptor of 
the file, buf is a pointer to the memory location to receive the bytes read, and n is a count of the 
desired number of bytes to be read. The function normally returns the same number of bytes as 
requested, but will return fewer if the file does not have that many bytes left to be read. The 
function returns 0 if the file has reached its end, or —1 if an error is encountered. 


When the file is a terminal, read normally reads only up to the next newline. 


The number of bytes to be read is arbitrary. The two most common values are 1, which means one 
character at a time, and 1024, which corresponds to the physical block size on many peripheral 
devices. 
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2.6.4 Writing Bytes to a File 


The write function writes one or more bytes from a given memory location to a given file. The 
function call has the form: 


n_written = write(fd, buf, n); 


where n_ written is the variable to receive a count of bytes actually written, fd is the file descriptor 
of the file, bufis the name of the buffer containing the bytes to be written, and 7 is the number of 
bytes to be written. 


The function always returns the number of bytes actually written. It is considered an error if the 
return value is not equal to the number of bytes requested to be written. 


The number of bytes to be written is arbitrary. The two most common values are 1, which means 
one character at a time and 512, which corresponds to the physical block size on many peripheral 
devices. 


2.6.5 Closing a File 


The close function breaks the connection between a file descriptor and an open file, and frees the 
file descriptor for use with some other file. The function call has the form: 


close (fd) 


where fd is the file descriptor of the file to close. The function normally returns 0, but will return 
—1 if anerror is encountered. 


The function is typically used to close files that are not longer needed. For example, the following 
program fragment closes the standard input if the argument count is greater than 1. 


int fd; 
if (argc >1) 
close( 0 ); 


Note that all open files in a program are closed when a program terminates normally or when the 
exit function is called, so no explicit call to close is required. 


2.6.6 Program Examples 


This section shows how to use the low-level functions to perform useful tasks. It presents three 
examples that incorporate the functions as the sole method of input and output. 


The first program copies its standard input to its standard output. 


main() /* copy input to output */ 


char buf[ BUFSIZ ]; 
int n; 


while ((n = read( 0, buf, BUFSIZ )) > 0) 
write(1, buf, n); 
exit(0); 
} 


The program uses the read function to read BUFSIZE bytes from the standard input (file 
descriptor 0). It then uses write to write the same number of bytes it read to the standard output 
(file descriptor 1). If the standard input file size is not a multiple of BUFSIZE, the last read 
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returns a smaller number of bytes to be written by write, and the next call to read returns zero. 


This program can be used like a copy command to copy the content of one file to another. You can 
do this by redirecting the standard input and output files. 


The second example shows how the read and write functions can be used to construct higher level 
functions like getchar and putchar. For example, the following is a version of getchar which 
performs unbuffered input: 


#define CMASK 0377 /* for making chars > 0 */ 
getchar() /* unbuffered single character input */ 
char c; 


return((read(0, &c, 1) > 0) ? c & CMASK : EOF); 


The variable “‘c” must be declared char, because read accepts a character pointer. In this case, 
the character being returned must be masked with octal 0377 to ensure that it is positive; 
otherwise sign extension may make it negative. 


The second version of getchar reads input in large blocks, but hands out the characters one at a 
time: 


#define CMASK 0377 /* for making char’s > 0 */ 
getchar() /* buffered version */ 
{ 

static char buf[BUFSIZ]; 

static char *bufp = buf; 

Static int n = 0; 


if(n==0){ /* buffer is empty */ 
n = read(0, buf, BUFSIZ); 
bufp = buf; 
} 
return((--n >= 0) ? *bufpt+ & CMASK : EOF); 
} 


Again, each character must be masked with the octal constant 0377. 


The final example is a simplified version of the XENIX utility, cp, a program that copies one file to 
another. The main simplification is that this version copies only one file, and does not permit the 
second argument to bea directory. 
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#define NULL 0 
#define PMODE 0644 /* RW for owner, R for group, others */ 


main(argc, argv) (ep: copy (1 to 42) */ 
int argc; 
char *argv[]; 


int Dito 
char buf[ BUFSIZ ]; 


if (arge != 3) 
error("Usage: cp from to", NULL); 
if ((f1 = open(argv[1], O RDONLY)) == —-1) 


error("cp: can’t open %s", argv[1]); 
if ((f2 = open(argv[2], O CREAT |O WRONLY, 
PMODE)) == —1) 
error("cp: can’t create %s", argv[2]); 


while ((n = read(fl, buf, BUFSIZ)) > 0) 
if (write(f2, buf, n) != n) 
error("cp: write error", NULL); 
exit(0); 


error(sl, s2) /* print error message and die */ 
ear slo *S2% 
{ 

printf(sl, s2); 

printf("\n"); 

exit(1); 


There is a limit (usually 20) to the number of files that a program may have open simultaneously. 
Therefore, any program which intends to process many files must be prepared to reuse file 
descriptors by closing unneeded files. 


2.6.7 Using Random Access I/O 


Input and output operations on any file are normally sequential. This means each read or write 
takes place at the character position immediately after the last character read or written. The 
standard library, however, provides a number of stream and low-level functions that allow a 
program to access a file randomly, that is, to exactly specify the position it wishes to read from or 
write to next. 


The functions that provide random access operate on a file’s “character pointer”. Every open file 
has a character pointer that points to the next character to be read from that file, or the next place 
in the file to receive a character. Normally, the character pointer is maintained and controlled by 
the system, but the random access functions let a program move the pointer to any position in the 
file. 


2.6.8 Moving the Character Pointer 


The /seek function, a low-level function, moves the character pointer in a file opened for low-level 
access to a given position. The function call has the form: 


lseek(fd, offset, origin); 
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where fd is the file descriptor of the file, offset is the number of bytes to move the character 
pointer, and origin is the number that gives the starting point for the move. It may be 0 for the 
beginning of the file, 1 for the current position, and 2 for the end. iseek returns the new position in 
the file in a long. 


For example, this call forces the current position in the file whose descriptor is 3 to move to the 
512th byte from the beginning of the file. 


lseek( 3, (long)512, 0 ) 


Subsequent reading or writing will begin at that position. Note that offset must be a long integer 
and fd and origin must be integers. 


The function may be used to move the character pointer to the end of a file to allow appending, or 
to the beginning as in a rewind function. For example, the call 


lseek(fd, (long)0, 2); 
prepares the file for appending, and 
lseek(fd, (long)0, 0); 


rewinds the file (moves the character pointer to the beginning). Notice the “(long)0”’ argument; 
it could also be written as 


OL 


Using /seek it is possible to treat files more or less like large arrays, at the price of slower access. 
For example, the following simple function reads any number of bytes from any arbitrary place in 
a file: 


get(fd, pos, buf, n) /* read n bytes from position pos */ 
int fd, n; 

long pos; 

char *buf; 


{ 
Iseek(fd, pos, 0); /* get to pos */ 
return(read(fd, buf, n)); 


2.6.9 Moving the Character Pointer in a Stream 


The fseek function, a stream function, moves the character pointer in a file to a given location. 
The function call has the form: 


fseek (stream, offset, ptrname) 


where stream is the file pointer of the file, offset is the number of characters to move to the new 
position (it must be a long integer), and ptrname is the starting position in the file of the move (it 
must be “0” for beginning, “1”, for current position, or “2” for end of the file). The function 
normally returns zero, but will return the value EOF if an error is encountered. 


For example, the following program fragment moves the character pointer to the end of the file 
given by “stream”’. 


FILE *stream; 


fseek(stream, (long)0, 2); 


The function may be used on either buffered or unbuffered files. 
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2.6.10 Rewinding a File 


The rewind function, a stream function, moves the character pointer to the beginning of a given 
file. The function call has the form: 


rewind (stream) 
where stream is the file pointer of the file. The function is equivalent to the following function call 
fseek (stream,0L,0); 


It is chiefly used as a more readable version of the call. 
2.6.11 Getting the Current Character Position 


The ftell function, a stream function, returns the current position of the character pointer in the 
given file. The returned position is always relative to the beginning of the file. The function call 
has the form: 


p = ftell (stream) 


where stream is the file pointer of the file and p is the variable to receive the position. The return 
value is always a long integer. The function returns the value —1 if an error is encountered. 


The function is typically used to save the current location in the file so that the program can later 
return to that position. For example, the following program fragment first saves the current 
character position in “‘oldp’”, then restores the file to this position if the current character position 
is greater than “800”. 


FILE *outfile; 
long oldp; 
long ftell(); 


oldp = ftell( outfile ); 


if ((ftell( outfile )) > 800) 
fseek(outfile, oldp, 0); 
The ftell is identical to the function call 
lseek( fd, (long)0, 1) 


where fd is the file descriptor of the given stream file. 
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3.1 Introduction 


This chapter explains how to use the screen updating and cursor movement library named curses. 
The library provides functions to create and update screen windows, get input from the terminal 
in a screen-oriented way, and optimize the motion of the cursor on the screen. 


3.1.1 Screen Processing Overview 


Screen processing gives a program a simple and efficient way to use the capabilities of the 
terminal attached to the program’s standard input and output files. Screen processing does not 
rely on the terminal’s type. Instead the screen processing functions use the XENIX terminal 
capability file /etc/termcap to tailor their actions for any given terminal. This makes a screen 
processing program terminal-independent. The program can be run with any terminal as long as 
that terminal is described in the /etc/termcap file. 


The screen processing functions access a terminal screen by working through intermediate 
“screens” and “windows” in memory. A screen is a representation of what the entire terminal 
screen should look like. A window is a representation of what some portion of the terminal screen 
should look like. A screen can be made up of one or more windows. A window can be as small asa 
single character or as large as an entire screen. 


Before a screen or window can be used, it must be created by using the newwin or subwin 
functions. These functions define the size of the screen or window in terms of lines and columns. 
Each position in a screen or window represents a place for a single character and corresponds toa 
similar place on the terminal screen. Positions are numbered according to line and column. For 
example, the position in the upper left corner of a screen or window is numbered (0,0) and the 
position immediately to its right is (0,1). A typical screen has 24 lines and 80 columns. Its upper 
left corner corresponds to the upper left corner of the terminal screen. A window, on the other 
hand, may be any size (within the limits of the actual screen). Its upper left corner can 
correspond to any position on the terminal screen. For convenience, the initscr function which 
initializes a program for screen processing also creates a default screen , stdscr (for “standard 
screen’). The stdscr may be used without first creating it. The function also creates curscr (for 
“current screen’’) which contains a copy of what curses thinks is on the terminal screen. 


To display characters at the terminal screen, a program must write these characters to a screen or 
window using screen processing functions such as addch and waddch. If necessary, a program 
can move to the desired position in the screen or window by using the move and wmove functions. 
Once characters are added to a screen or window, the program can copy the characters to the 
terminal screen by using the refresh or wrefresh function. These functions update the terminal 
screen according to what has changed in the given screen or window. Since the terminal screen is 
not changed until a program calls refresh or wrefresh, a program can maintain several different 
windows, each containing different characters for the same portion of the terminal screen. The 
program can choose which window should actually be displayed before updating. 


A program can continue to add new characters to a screen or window as needed, and edit these 
characters by using functions such as insertln, deleteln, and clear. A program can also combine 
windows to make a composite screen using the overlay and overwrite functions. In each case, the 
refresh or wrefresh function is used to copy the changes to the terminal screen. 


3.1.2 Using the Library 


To use the curses library in a program, you must add the line 
#include <curses.h> 
to the beginning of your program. The curses.h file contains definitions for types and variables 


used by the library. 
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The actual screen processing functions are in the library files libcurses.a and libtermcap.a. 
These files are not automatically read when you compile your program, so you must include the 
appropriate library switches in your invocation of the compiler. The command line must have the 


form: 


cc file ... -lcurses -ltermcap 


where file is the name of the source file you wish to compile. You may given more than one 
filename if desired. You may also use other compiler options in the command line. For example, 


the command 


cc main.c intf.c -lcurses -ltermcap -o sample 


compiles the files main.c and intf.c, and copies the executable program to the file sample after 


linking the screen processing library files to the program. 


Note that the curses.h file automatically includes the file sgtty.h in your program. This file must 


not be included twice. 


The screen processing library has a variety of predefined names. These names refer to variables, 
manifest constants, and types that can be used with the library functions. The following is a list of 


these names. 


WINDOW* 


WINDOW* 


char* 


bool 


char* 


int 


int 


int 


int 


reg 
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Name 


bool 
TRUE 


curscr 


stdscr 


Def_term 


My _ term 


ttytype 
LINES 
COLS 
ERR 


OK 


Variables 


Description 


A pointer to the current version of 
the terminal screen. 

A pointer to the default screen 
used for updating when no explicit 
screen is defined. 

A pointer to the default terminal 
type if the type cannot be 
determined. 

The terminal type flag. If set, it 
causes the terminal specification in 
“Def_term” to be used, regardless 
of the real terminal type. 

A pointer to the full name of the 
current terminal. 

The number of lines on the 
terminal. 

The number of columns on the 
terminal. 

The error flag. Returned by 
functions on an error. 

The okay flag. Returned by 
functions on successful operation. 


Types and Constants 


Description 


A storage class. It is the same as 
register storage class. 

A type. It is the samea char type. 
The boolean true value (1). 
FALSE _ The boolean false value (0). 
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3.2 Preparing the Screen 


The initscr and endwin functions perform the operations required to initialize and terminate 
programs that use the screen processing functions. The following sections describe these 
functions and how they affect the terminal. 


3.2.1 Initializing the Screen 


The initscr function initializes screen processing for a program by allocating the required 
memory space for the screen processing functions and variables, and by setting the terminal to 
the proper modes. The function call has the form: 


initscr() 
No arguments are required. 


The initscr function must be used to prepare the program for subsequent calls to other screen 
processing functions and for use of the screen processing variables. For example, in the following 
program fragment initscr initializes the screening processing functions. 


#include <curses.h> 


main () 


initscr(); 
if ( cmpstr(ttytype,"dumb") ) 
fprintf(stderr, "Terminal type can’t display screen."); 


In this example, the predefined variable “ttytype”’ is checked for the current terminal type. 


The function returns (WINDOW*) ERR if memory allocation causes an overflow. 
3.2.2 Using Terminal Capability and Type 


The initscr function uses the terminal capability descriptions given in the XENIX system’s 
/etc/termcap file to prepare the screen processing functions for creating and updating terminal 
screens. The descriptions define the character sequences required to perform a given operation on 
a given terminal. These sequences are used by the screen processing functions to add, insert, 
delete, and move characters on the screen. The descriptions are automatically read from the file 
when screen processing is initialized, so direct access by a program is not required. 


The initscr function uses the shell’s ““TERM7” variable to determine which terminal capability 
description to use. The “TERM” variable is usually assigned an identifier when a user logs in. 
This identifier defines the terminal type and is associated with a terminal capability description in 
the /etc/termcap file. 


If the “TERM” variable has no value, the functions use the default terminal type in the library’s 
predefined variable “Def term”. This variable initially has the value “dumb” (for “dumb 
terminal’’), but the user may change it to any desired value. This must be done before calling the 
initscr function. 


In some cases, it is desirable to force the screen processing functions to use the default terminal 
type. This can be done by setting the library’s predefined variable “My_ term” tothe value 1. The 
full name of the current terminal is stored in the predefined variable “ttytype’’. 


Terminal capabilities, types, and identifiers are described in detail in termcap(F) in the XENIX 
Reference Manual. 
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3.2.3 Using Default Terminal Modes 


The initscr function automatically sets a terminal to default operation modes. These modes 
define how the terminal displays characters sent to the screen and how it responds to characters 
typed at the keyboard. The initscr function sets the terminal to ECHO mode which causes 
characters typed at the keyboard to be displayed at the screen, and RAW mode which causes 
characters to be used as direct input (no editing or signal processing is done). 


The default terminal modes can be changed by using the appropriate functions described in the 
section “Setting a Terminal Mode” in this chapter. If the modes are changed, they must be 
changed immediately after calling initscr. Terminal modes are described in detail in tty(M) in 
the XENIX Reference Manual. 


Note 


The terminal mode functions should only be used in conjunction with other screen 
processing functions. They should not be used alone. 


3.2.4 Using Default Window Flags 


The initscr function automatically clears the cursor, scroll, and clear flags of the standard screen 
to their default values. These flags, called the window flags, define how the refresh function 
affects the terminal screen when refreshing from the standard screen. When clear, the cursor flag 
prevents the terminal’s cursor from moving back to its original location after the screen is 
updated, the scroll flag prevents scrolling on the screen, and the clear flag prevents the characters 
on the screen from being cleared before being updated. The flags may be changed by using the 
functions described in the section “Setting Window Flags,” in this chapter. 


3.2.5 Using the Default Terminal Size 


The initscr function sets the terminal screen size to a default number of lines and columns. The 
default values are given in the predefined variables “LINES” and “COLS”’.. You can change the 
default size of a terminal by setting the variables to new values. This should be done before the 
first call to initscr. If it is done after the first call, a second call to initscr must be made to delete 
the existing standard screen and create a new one. 


3.2.6 Terminating Screen Processing 


The endwin function terminates the screen processing in a program by freeing all memory 
resources allocated by the screen processing functions and restoring the terminal to the state 
before screen processing began. The function call has the form: 


endwin() 
No arguments are required. 


The endwin function must be used before leaving a program that has called the initscr function to 
restore the terminal to its previous state. The function is generally the last function call in the 
program. For example, in the following program fragment initscr and endwin form the 
beginning and end of the program. 


Screen Processing 


#include <curses.h> 


main () 


initscr(); 
/* Program body. */ 
endwin(); 


Note that endwin must not be called if initscr has not been called. Also, endwin should be called 
before any call to the exit function. The endwin function must also be called if the gettmode and 
setterm functions have been called even if initscr has not. 


3.3 Using the Standard Screen 


The following sections explain how to use the standard screen to display and edit characters on 
the terminal screen. 


3.3.1 Adding a Character 


The addch function adds a given character to the standard screen and moves the character 
pointer one position to the right. The function call has the form: 


addch( ch ) 


where ch gives the character to be added and must have char type. For example, if the current 
position is (0, 0), the function call 


addch(’A’) 
places the letter ““A”’ at this position and moves the pointer to (0, 1). 


If a newline (’\n’) character is given, the function deletes all characters from the current position 
to the end of the line and moves the pointer one line down. If the newline flag is set, the function 
deletes the characters and moves the pointer to the beginning of the next line. If a return (’\r’) is 
given, the function moves the pointer to the beginning of the current line. If a tab (’\t’) is given, 
the function moves the pointer to the next tab stop, adding enough spaces to fill the gap between 
the current position and the stop. Tab stops are placed at every eight character positions. 


The function returns ERR if it encounters an error, such as illegal scrolling. 


3.3.2 Adding a String 


The addstr function adds a string of characters to the standard screen, placing the first character 
of the string at the current position and moving the pointer one position to the right for each 
character in the string. The function call has the form: 


addstr( str ) 


where str is a character pointer to the given string. For example, if the current position is (0,0), 
the function call 


addstr("line"); 
places the beginning of the string “line” at this position and moves the pointer to (0,4). 


If the string contains newline, return, or tab characters, the function performs the same actions as 
described for the addch function. If the string does not fit on the current line, the string is 
truncated. 
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The function returns ERR if it encounters an error such as illegal scrolling. 
3.3.3 Printing Strings, Characters, and Numbers 


The printw function prints one or more values on the standard screen, where a value may be a 
string, a character, or a decimal, octal, or hexadecimal number. The function call has the form: 


printw( fmt [, arg | ...) 


where fmt is a pointer to a string that defines the format of the values, and arg is a value to be 
printed. If more than one arg is given, each must be separated from the preceding argument with 
a comma (,). For each arg given, there must be a corresponding format given in fmt. A format 
may be “%s”’ for string, “%c’’ for character, and “%d”’, ““%o”’, or “%x” for a decimal, octal, or 
hexadecimal number, respectively. (Other formats are described in printf(S) in the XENIX 
Reference Manual.) If “%s” is given, the corresponding arg must be a character pointer. For 
other formats, the actual value or a variable containing the value may be given. 


The function is typically used to copy both numbers and strings to the standard screen at the same 
time. For example, if the current position is (0,0), the function call 


printw("%s %d", name, 15); 


prints the name given by the variable “name” starting at position (0,0). It then prints the number 
“15” immediately after the name. 


The function returns ERR if it encounters an error such as illegal scrolling. 
3.3.4 Reading a Character From the Keyboard 


The getch function reads a single character from the terminal keyboard and returns the 
character asa value. The function call has the form: 


c = getch() 
where c is the variable to receive the character. 


The function is typically used to read a series of individual characters. For example, in the 
following program fragment, characters are read and stored until a newline or the end of the file 
is encountered, or until the buffer size has been reached. 


char c, p[ MAX]; 


int 1; 


1 = 0; 
while ((c=getch()) != \n’. && c!= EOF && i <MAX ) 
plit+] =; 


If the terminal is set to ECHO mode, getch copies the character to the standard screen; otherwise, 
the screen remains unchanged. If the terminal is not set to RAW or NOECHO mode, getch 
automatically sets the terminal to CBREAK mode, then restores the previous mode after reading 
the character. Terminal modes are described later in the chapter. 


The function returns ERR if it encounters an error such as illegal scrolling. 


3.3.5 Reading a String From the Keyboard 


The getstr function reads a string of characters from the terminal keyboard and copies the string 
toa given location. The function call has the form: 
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getstr( str ) 


where str is a character pointer to the variable or location to receive the string. When typed at the 
keyboard, the string must end with a newline character or with the end-of-file character. The 
extra character is replaced by a null character when the string is stored. It is the programmer’s 
responsibility to ensure that str has adequate space to store the typed string. 


The function is typically used to read names and other text from the keyboard. For example, in 
the following program fragment, reads a filename from the keyboard and stores it in the array 
“name”’. 


char name[20]; 


getstr(name); 


If the terminal is set to ECHO mode, getstr copies the string to the standard screen. If the 
terminal is not set to RAW or NOECHO mode, the function automatically sets the terminal to 
CBREAK mode, then restores the previous mode after reading the character. Terminal modes 
are described later in the chapter. 


The function returns ERR if it encounters an error such as illegal scrolling. 


3.3.6 Reading Strings, Characters, and Numbers 


The scanw function reads one or more values from the terminal keyboard and copies the values to 
given locations. A value may be a string, character, or decimal, octal, or hexadecimal number. 
The function call has the form: 


scanw( fmt, argptr ... ) 


where fmt is a pointer to a string defining the format of the values to be read, and argptr is a 
pointer to the variable to receive a value. If more than one argptr is given, each must be separated 
from the preceding item with a comma (,). For each argptr given, there must be a corresponding 
format given in fmt. A format may be “%s” for string, ““%c” for character, and “%d”’, ““%o”’, or 
““%x’’ for a decimal, octal, or hexadecimal number, respectively. (Other formats are described in 
scanf(S) in the XENIX Reference Manual.) 


The function is typically used to read a combination of strings and numbers from the keyboard. 
For example, in the following program fragment scanw reads a name and a number from the 
keyboard. 


char name[20]; 
int id; 
scanw("%s %d", name, &id); 


In this example, the input values are stored in the character array “name” and the integer 
variable “‘id”’. 


If the terminal is set to ECHO mode, the function copies the string to the standard screen. If the 
terminal is not set to RAW or NOECHO mode, the function automatically sets the terminal to 
CBREAK mode, then restores the previous mode after reading the character. 


The function returns ERR if it encounters an error such as illegal scrolling. 


3.3.7 Moving the Current Position 


The move function moves the pointer to the given position. The function call has the form: 
move (y, x) 


where y is an integer value giving the new row position, and x is an integer value giving the new 
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column position. For example, if the current position is (0,0), the function call 
move(5,4) 
moves the pointer to line 5, column 4. 


The function returns ERR if it encounters an error such as illegal scrolling. 


3.3.8 Inserting a Character 


The insch function inserts a character at the current position and shifts the existing character 
(and all characters to its right) one position to the right. The function call has the form: 


insch ( c ) 
where cis the character to be inserted. 


The function is typically used to insert a series of characters into an existing line. For example, in 
the following program fragment insch is used to insert the number of characters given by “‘cnt” 
into the standard screen a the current position. 


int cnt; 


char *string; 


while ( cnt !=0 ) { 
insch(string[cnt]); 
cnt--; 


} 


The function returns ERR if it encounters an error such as illegal scrolling. 


3.3.9 Inserting a Line 


The insert/n function inserts a blank line at the current position and moves the existing line (and 
all lines below it) down one line, causing the last line to move off the bottom of the screen. The 
function call has the form: 


insertln() 
No arguments are required. 


The function is used to insert additional lines of text in the standard screen. For example, in the 
following program fragment insert/n is used to insert a blank line when the count in “cnt” is equal 
to. 79, 


int cnt; 


if ( cnt == 79 ) 
insertln(); 


The function returns ERR if it encounters an error such as illegal scrolling. 


3.3.10 Deleting a Character 


The delch function deletes the character at the current position and shifts the character to the 
right of the deleted character (and all characters to its right) one position to the left. The last 
character on the line is replaced by a space. The function call has the form: 


delch() 


No arguments are required. 
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The function is typically used to delete a series of characters from the standard screen. For 
example, in the following program fragment delch deletes the character at the current position as 
long as the count in “‘cnt”’ is not 0. 


int cnt; 
while ( cnt != 0 ) { 
delch(); 


cnt-- ; 


} 
3.3.11 Deleting a Line 


The deleteln function deletes the current line and shifts the line below the deleted line (and all 
lines below it) one line up, leaving the last line on the screen blank. The function call has the 
form: 


deleteln() 
No arguments are required. 


The delete/n function is used to delete existing lines from the standard screen. For example, in 
the following program fragment delete/n is used to delete a line from the standard screen if the 
count in “cnt” is 79. 


int cnt; 


if ( cnt == 79 ) 
deleteln(); 


3.3.12 Clearing the Screen 


The clear and erase functions clear all characters from the standard screen by replacing them 
with spaces. The functions are typically used to prepare the screen for new text. 


The clear function clears all characters from the standard screen, moves the pointer to (0,0), and 
sets the standard screen’s clear flag. The flag causes the next call to the refresh function to clear 
all characters from the terminal screen. 


The erase function clears the standard screen, but does not set the clear flag. For example, in the 
following program fragment clear clears the screen if the input value is 12. 


char c; 


if ((c=getch()) == 12) 
clear(); 


3.3.13 Clearing a Part of the Screen 


The c/rtobot and cl/rtoeol functions clear one or more characters from the standard screen by 
replacing the characters with spaces. The functions are typically used to prepare a part of the 
standard screen for new characters. 


The c/rtobot function clears the screen from the current position to the bottom of the screen. For 
example, if the current position is (10,0), the function call 


clrtobot(); 


clears all characters from line 10 and all lines below line 10. 
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The c/rtoeol function clears the standard screen from the current position to the end of the 
current line. For example, if the current position is (10,10), the function call 


clrtoeol(); 


clears all characters from (10,10) to (10,79). The characters at the beginning of the line remain 
unchanged. 


Note that both the c/rtobot and c/rtoeol functions do not change the current position. 
3.3.14 Refreshing From the Standard Screen 


The refresh function updates the terminal screen by copying one or more characters from the 
standard screen to the terminal. The function effectively changes the terminal screen to reflect 
the new contents of the standard screen. The function call has the form: 


refresh() 
No arguments are required. 


The function is used solely to display changes to the standard screen. The function copies only 
those characters that have changed since the last call to refresh and leaves any existing text on the 
terminal screen. For example, in the following program fragment refresh is called twice. 


addstr("The first time.\n"); 
refresh(); 

addstr("The second time.\n"); 
refresh(); 


In this example, the first call to refresh copies the string ““The first time.” to the terminal screen. 
The second call copies only the string “The second time.” to the terminal, since the original string 
has not been changed. 


The function returns ERR if it encounters an error such as illegal scrolling. If an error is 
encountered, the function attempts to update as much of the screen as possible without causing 
the scroll. 


3.4 Creating and Using Windows 


The following sections explain how to create and use windows to display and edit text on the 
terminal screen. 


3.4.1 Creating a Window 


The newwin function creates a window and returns a pointer that may be used in subsequent 
screen processing functions. The function call has the form: 


win = newwin( lines, cols, begin_y, begin x ) 


where win is the pointer variable to receive the return value, /ines and cols are integer values that 
give the total number of lines and columns, respectively, in the window, and begin _y and begin x 
are integer values that give the line and column positions, respectively, of the upper left corner of 
the window when displayed on the terminal screen. The win variable must have type 
WINDOW*. 


The function is typically used in programs that maintain a set of windows, displaying different 
windows at different times or alternating between window as needed. For example, in the 
following program fragment newwin creates a new window and assigns the pointer to this window 
to the variable midscreen. 
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WINDOW *midscreen; 


midscreen = newwin(5, 10, 9, 35); 


The window has 5 lines and 10 columns. The upper left corner of the window is placed at the 
position (9,35) on the terminal screen. 


If either lines or cols is zero, the function automatically creates a window that has “LINES - 
begin_y” lines or “COLS - begin_x’’ columns, where “LINES” and “COLS” are the predefined 
constants giving the total number of lines and columns on the terminal screen. For example, the 
function call 


newwin(0, 0, 0, 0) 


creates a new window whose upper left corner is at position (0,0) and that has “LINES” lines and 
“COLS” columns. 


Note 


You must not create windows that exceed the dimensions of the actual screen. 


The newwin function returns the value (WINDOW*) ERR on an error, such as insufficient 
memory for the new window. 


3.4.2 Creating a Subwindow 


The subwin function creates a subwindow and returns a pointer to the new window. A 
subwindow is a window which shares all or part of the character space of another window and 
provides an alternate way to access the characters in that space. The function call has the form: 


swin = subwin( win, lines, cols, begin _y, begin x) 


where swin is the pointer variable to receive the return value, win is the pointer to the window to 
contain the new subwindow, /ines and cols are integer values that give the total number of lines 
and columns, respectively, in the subwindow, and begin y and begin x are integer values that 
give the line and column position, respectively, of the upper left corner of the subwindow when 
dislayed on the terminal screen. The swin variable must have type WINDOW*. 


The function is typically used to divide a large window into separate regions. For example, in the 
following program fragment subwin creates the subwindow named “cmdmenu’” in the lower part 
of the standard screen. 


WINDOW *cmdmenu; 


cmdmenu = subwin(stdscr, 5, 80, 19, 0); 
In this example, changes to “cmdmenu” affect the standard screen as well. 


The subwin function returns the value (WINDOW*) ERR on an error, such as insufficient 
memory for the new window. 


3.4.3, Adding and Printing to a Window 


The waddch, waddstr, and wprintw functions add and print characters, strings, and numbers toa 
given window. 
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The waddch function adds a given character to the given window and moves the character pointer 
one position to the right. The function call has the form: 


waddch( win, ch ) 


where win is a pointer to the window to receive the character, and ch gives the character to be 
added; ch must have char type. For example, if the current position in the window “‘midscreen’”’ is 
(0,0), the function call 


waddch(midscreen, ’A’) 
places the letter “A” at this position and moves the pointer to (0,1). 


The waddstr function adds a string of characters to the given window, placing the first character 
of the string at the current position and moving the pointer one position to the right for each 
character in the string. The function call has the form: 


waddstr( win, str ) 


where win is a pointer to the window to receive the string, and str is a character pointer to the 
given string. For example, if the current position is (0,0), the function call 


waddstr(midscreen, "line"); 
places the beginning of the string “line” at this position and moves the pointer to (0,4). 


The wprintw function prints one or more values on the given window, where a value may be a 
string, a character, or a decimal, octal, or hexadecimal number. The function call has the form: 


wprintw( win, fmt [, arg | ...) 


where win is a pointer to the window to receive the values, fmt is a pointer to a string that defines 
the format of the values, and arg is a value to be printed. If more than one arg is given, each must 
be separated from the preceding with a comma (,). For each arg given, there must be a 
corresponding format given in fmt. A format may be “%s”’ for string, ““%c’”’ for character, and 
“Zod”, “%oo”’, or “Yox”’ for a decimal, octal, or hexadecimal number, respectively. (Other formats 
are described in printf(S) in the XENIX Reference Manual.) If “%s”’ is given, the corresponding 
arg must be a character pointer. For other formats, the actual value or a variable containing the 
value may be given. 


The function is typically used to copy both numbers and strings to the standard screen at the same 
time. For example, in the following program fragment wprintw prints a name and then the 
number “15” at the current position in the window “‘midscreen”’. 


char *name; 


wprintw(midscreen, "%s %d", name, 15); 


Note that when a newline, return, or tab character is given to a waddch, waddstr, or wprintw 
function, the functions perform the same actions as described for the addch function. The 
functions return ERR if they encounter errors such as illegal scrolling. 


3.4.4 Reading and Scanning for Input 


The wgetch, wgetstr, and wscanw functions read characters, strings, and numbers from the 
standard input file and usually echo the values by copying them to the given window. 


The wgetch function reads a single character from the standard input file and returns the 
character as a value. The function call has the form: 


c = wgetch( win ) 


where win is a pointer to a window, and c is the character variable to receive the character. 
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The function is typically used to read a series of characters from the keyboard. For example, in 
the following program fragment wgetch reads characters until a colon (:) is found. 


char c, dir[MAX]; 
int 1; 


1 = 0; 
while ((c=wgetch(cmdmenu)) !=’? && i <MAX) 
dir[i++] = c; 


The wgetstr function reads a string of characters from the terminal keyboard and copies the 
string toa given location. The function call has the form: 


weetstr( win, str ) 


where win is a pointer to a window, and str is a character pointer to the variable or location to 
receive the string. When typed at the keyboard, the string must end with a newline character or 
with the end-of-file character. The extra character is replaced by a null character when the string 
is stored. It is the programmer’s responsibility to ensure that str has adequate space for storing 
the typed string. 


The function is typically used to read names and other text from the keyboard. For example, in 
the following program fragment wgetstr reads a string from the keyboard and stores it in the 
array “‘filename”’. 


char filename[20]; 


wegetstr(cmdmenu, filename); 


The wscanw function reads one or more values from the standard input file and copies the values 
to given locations. A value may be a string, a character, or a decimal, octal, or hexadecimal 
number. The function call has the form: 


wscanw( win, fmt [, argptr | ... ) 


where win is a pointer to a window, fmt is a pointer to a string defining the format of the values to 
be read, and argptr is a pointer to the variable to receive a value. If more than one argptr is given, 
each must be separated from the preceding by a comma (,). For each argptr given, there must be 
a corresponding format given in fmt. A format may be “%s’”’ for string, “%c’”’ for character, and 
“%d”’, “%o’’, or ““%x” for a decimal, octal, or hexadecimal number, respectively. (Other formats 
are described in scanf(S) in the XENIX Reference Manual.) 


The function is typically used to read a combination of strings and numbers from the keyboard. 
For example, in the following program fragment wscanw reads a name and a number from the 
keyboard. 


char name[20]; 
int id; 
wscanw(midscreen, "%s %d", name, &id); 


In this example, the name is stored in the character array “name” and the number in the integer 
variable “‘id”’. 


If the terminal is set to ECHO mode, the function copies the string to the given window. If the 
terminal is not set to RAW or NOECHO mode, the function automatically sets the terminal to 
CBREAK mode, then restores the previous mode after reading the character. 


The functions return ERR if they encounter errors such as illegal scrolling. 
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3.4.5 Moving a the Current Position in a Window 


The wmove function moves the current position in a given window. The function call has the 
form: 


wmove (win, y, x) 


where win is a pointer to a window, y is an integer value giving the new line position, and x is an 
integer value giving the new column position. For example, the function call 


wmove(midscreen, 4, 4) 
moves the current position in the window “midscreen” to (4,4). 


The function returns ERR if it encounters an error such as illegal scrolling. 
3.4.6 Inserting Characters 


The winsch and winsert/n functions insert characters and lines into a given window. 


The winsch function inserts a character at the current position and shifts the existing character 
(and all characters to its right) one position to the right. The function call has the form: 


winsch ( win, c ) 
where win is a pointer to a window, and cis the character to be inserted. 


The function is typically used to edit the contents of the given window. For example, the function 
call 


winsch(midscreen, ’X’); 
inserts the character “X”’ at the current position in the window “‘midscreen”’. 


The winsertln function inserts a blank line at the current position and moves the existing line (and 
all lines below it) down one line, causing the last line to move off the bottom of the screen. The 
function call has the form: 


winsertln( win ) 
where win is a pointer to the window to receive the blank line. 


The function is used to insert lines into a window. For example, in the following program 
fragment winsert/n inserts a blank line at the top of the window “cmdmenu” preparing it for a 
new line. 


char line[80]; 
wmove(cmdmenu, 3, 0); 


winsertlIn(cmdmenu); 
waddstr(cmdmenu, line); 


Both functions return ERR if they encounter errors such as illegal scrolling. 
3.4.7 Deleting Characters and Lines 


The wdelch and wdeleteln functions delete characters and lines from the given window. 


The wdelch function deletes the character at the current position and shifts the character to the 
right of the deleted character (and all characters to its right) one position to the left. The last 
character on the line is replaced with a space. The function call has the form: 


wdelch( win ) 


3-14 


Screen Processing 


where win is a pointer to a window. 


The function is typically used to edit the contents of the standard screen. For example, the 
function call 


wdelch(midscreen); 
deletes the character at the current position in the window “‘midscreen”’. 


The wdeleteln function deletes the current line and shifts the line below the deleted line (and all 
lines below it) one line up, leaving the last line in the screen blank. The function call has the form: 


wdeleteln( win ) 
where win is a pointer toa window. 


The function is typically used to delete existing lines from a given window. For example, in the 
following program fragment wdelete/n deletes the lines in “‘midscreen”’ until “cnt” is equal to 
zero. 


int cnt; 
while ( cnt != 0 ) { 


wdeleteln(midscreen); 
cnt--; 


3.4.8 Clearing the Screen 


The wclear, werase, wclrtobot, and wclrtoeol functions clear all or part of the characters from 
the given window by replacing them with spaces. The functions are typically used to prepare the 
window for new text. 


The wclear function clears all characters from the window, moves the pointer to (0,0), and sets 
the standard screen’s clear flag. The flag causes the next refresh function call to clear all 
characters from the terminal screen. The function call has the form: 


wclear( win ) 
where win is the window to be cleared. 


The werase function clears the given window, moves the pointer to (0,0), but does not set the clear 
flag. It is used whenever the contents of the terminal screen must be preserved. The function call 
has the form: 


werase( win ) 
where win is a pointer to the window to be cleared. 


The welrtobot function clears the window from the current position to the bottom of the screen. 
The function call has the form: 


welrtobot( win ) 


where win is a pointer to the window to be cleared. For example, if the current position in the 
window “midscreen” is (10,0), the function call 


wclrtobot( midscreen ); 
clears all characters from line 10 and all lines below line 10. 


The wclrtoeol function clears the standard screen from the current position to the end of the 
current line. The function call has the form: 


welrtoeol( win ) 
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where win is a pointer to the window to be cleared. For example, if the current position in 
“‘midscreen”’ is (10,10), the function call 


wclrtoeol( midscreen ); 


clears all characters from (10,10) to the end of the line. The characters at the beginning of the 
line remain unchanged. 


Note that the wc/rtobot and wclrtoeol functions do not change the current position. 


3.4.9 Refreshing From a Window 


The wrefresh function updates the terminal screen by copying one or more characters from the 
given window to the terminal. The function effectively changes the terminal screen to reflect the 
new contents of the window. The function call has the form: 


wrefresh( win ) 
where win is a pointer to a window. 


The function is used solely to display changes to the window. The function copies only those 
characters that have changed since the last call to wrefresh and leaves any existing text on the 
terminal screen. For example, in the following program fragment wrefresh is called twice. 


waddstr(cmdmenu, "Type a command name\n"); 
wrefresh(cmdmenu); 

waddstr(cmdmenu, "Command: "); 
wrefresh(cmdmenu); 


In this example, the first call to wrefresh copies the string “Type a command name” to the 
terminal screen. The second call copies only the string ““Command:”’ to the terminal, since the 
original string has not been changed. 


Note 


If curscr is given with wrefresh, the function restores the actual screen to its most 
recent contents. This is useful for implementing a “redraw” feature for screens that 
become cluttered with unwanted output. 


The function returns ERR if it encounters an error such as illegal scrolling. If an error is 
encountered, the function attempts to update as much of the screen as possible without causing 
the scroll. 


3.4.10 Overlaying Windows 


The overlay function copies all characters, except spaces, from one window to another, moving 
characters from their original positions in the first window to identical positions in the second. 
The function effectively lays the first window over the second, letting characters in the second 
window that would otherwise be covered by spaces remain unchanged. The function call has the 
form: 


overlay( winl, win2) 


where win] is a pointer to the window to be copied, and win2 is a pointer to the window to receive 
the copied text. The starting positions of win] and win2 must match, otherwise an error occurs. 
If winl is larger than win2, the function copies only those lines and columns in win] that fit in 
wind. 
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The function is typically used to build a composite screen from overlapping windows. For 
example, in the following program fragment overlay is used to build the standard screen from 
two different windows. 


WINDOW “*info, *cmdmenu; 


overlay(info, stdscr); 
overlay(cmdmenu, stdscr); 
refresh(); 


3.4.11 Overwriting a Screen 


The overwrite function copies all characters, including spaces, from one window to another, 
moving characters from their positions in the first window to identical positions in the second. 
The function effectively writes the contents of the first window over the second, destroying the 
previous contents of the second window. The function call has the form: 


overwrite( winl, win2 ) 


where win] is a pointer to the window to be copied, and win2 is a pointer to the window to receive 
the copied text. If win/ is larger than win2, the function copies only those lines and columns in 
win that fit in win2. 


The function is typically used to display the contents of a temporary window in the middle of a 
larger window. For example, in the following program fragment overwrite is used to copy the 
contents of a work window to the standard screen. 


WINDOW *work; 


overwrite(work, stdscr); 
refresh(); 


3.4.12 Moving a Window 


The mvwin function moves a given window to a new position on the terminal screen, causing the 
upper left corner of the window to occupy a given line and column position. The function call has 
the form: 


mvwin( win, y, x) 


where win is a pointer to the window to be moved, y is an integer value giving the line to which the 
corner is to be moved, and x is an integer value giving the column to which the corner is to be 
moved. 


The function is typically used to move a temporary window when an existing window under it 
contains information to be viewed. For example, in the following program fragment mvwin 
moves the window named “‘work”’ to the upper left corner of the terminal screen. 


WINDOW *work; 


mvwin(work, 0,0); 


The function returns ERR if it encounters a error such as an attempt to move part of a window off 
the edge of the screen. 


3.4.13 Reading a Character From a Window 


The inch and winch functions read a single character from the current pointer position in a 
window or screen. 
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The inch function reads a character from the standard screen. The function call has the form: 
c = inch() 
where cis the character variable to receive the character read. 


The winch function reads a character from a given window or screen. The function call has the 
form: 


c = winch( win ) 
where win is the pointer to the window containing the character to be read. 


The functions are typically used to compare the actual contents of a window with what is 
assumed to be there. For example, in the following program fragment inch and winch are used to 
compare the characters at position (0,0) in the standard screen and in the window named 
“altscreen”’. 


char ¢1,c2: 
cl = inch(); 
c2 = winch(altscreen); 


if (cl '=c2 ) 
error(); 


Note that reading a character from a window does not alter the contents of the window. 
3.4.14 Touching a Window 


The touchwin function makes the entire contents of a given window appear to be modified, 
Causing a subsequent refresh call to copy all characters in the window to the terminal screen. The 
function call has the form: 


touchwin( win ) 
where win is a pointer to the window to be touched. 


The function is typically used when two or more overlapping windows make up the terminal 
screen. For example, the function call 


touchwin(leftscreen); 


is used to touch the window named “‘leftscreen”. A subsequent refresh copies all characters in 
“‘leftscreen”’ to the terminal screen. 


3.4.15 Deleting a Window 


The delwin function deletes a given window from memory, freeing the space previously occupied 
by the window for other windows or for dynamically allocated variables. The function call has the 
form: 


delwin( win ) 
where win is the pointer to the window to be deleted. 


The function is typically used to remove temporary windows from a program or to free memory 
space for other uses. For example, the function call 


delwin(midscreen); 


removes the window named “‘midscreen’’. 
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3.5 Using Other Window Functions 


The following sections explain how to perform a variety of operations on existing windows, such 
as setting window flags and drawing boxes around the window. 


3.5.1 Drawing a Box 


The box function draws a box around a window using the given characters to form the horizontal 
and vertical sides. The function call has the form: 


box( win, vert, hor ) 


where win is the pointer to the desired window, vert is the vertical character, and hor is the 
horizontal character. Both ver and hor must have char type. 


The function is typically used to distinguish one window from another when combining windows 
ona single screen. For example, in the following program fragment box creates a box around the 
window in the lower half of the screen. 


WINDOW *cmdmenu; 
cmdmenu = subwin(stdscr, 5, 80, 19, 0); 
box(cmdmenu, 7, ’-’); 


If necessary, the function will leave the corners of the box blank to prevent illegal scrolling. 


3.5.2 Displaying Bold Characters 


The standout and wstandout functions set the standout character attribute, causing characters 
subsequently added to the given window or screen to be displayed as bold characters. 


The standout function sets the standout attribute for characters added to the standard screen. 
The function call has the form: 


standout() 
No arguments are required. 


The wstandout function sets the standout attribute of characters added to the given window or 
screen. The function call has the form: 


wstandout( win ) 
where win is a pointer to a window. 


The functions are typically used to make error messages or instructions clearly visible when 
displayed at the terminal screen. For example, in the following program fragment standout sets 
the standout character attribute before adding an error message to the standard screen. 


if (code = 5 ) { 
standout(); 
addstr("Illegal character.\n"); 


Note that the actual appearence of characters with the standout attribute depends on the given 
terminal. This attribute is defined by the SO and SE (or US and UE) sequences given in the 
terminal’s termcap entry (see termcap(M) in the XENIX Reference Manual). 
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3.5.3 Restoring Normal Characters 


The standend and wstandend functions restore the normal character attribute, causing 
characters subsequently added to a given window or screen to be displayed as normal characters. 


The standend function restores the normal attribute for the standard screen. The function call 
has the form: 


standend() 
No arguments are required. 


The wstandend function restores the normal attribute for a given window or screen. The function 
call has the form: 


wstandend( win ) 
where win is a pointer to a window. 


The functions are typically used after an error message or instructions have been added to a 
screen using the standout attribute. For example, in the following program fragment standend 
restores the normal attribute after an error message has been added to the standard screen. 
if (code = 5) { 
standout(); 
addstr("Illegal character.\n"); 
standend(); 


3.5.4 Getting the Current Position 


The getyx function copies the current line and column position of a given window pointer to a 
corresponding pair of variables. The function call has the form: 


getyx( win, y, x ) 


where win is a pointer to the window containing the pointer to be examined, y is the integer 
variable to receive the line position, and x is the integer variable to receive the column position. 


The function is typically used to save the current position so that the program can return to the 
position at a later time. For example, in the following program fragment getyx saves the current 
line and column position in the variables “line” and “‘column’’. 


int line, column; 


getyx(stdscr, line, column); 
3.5.5 Setting Window Flags 


The /eaveok, scrollok, and clearok functions set or clear the cursor, scroll, and clear-screen flags. 
The flags control the action of the refresh function when called for the given window. 


The /eaveok function sets or clears the cursor flag which defines how the refresh function places 
the terminal cursor and the window pointer after updating the screen. If the flag is set, refresh 
leaves the cursor after the last character to be copied and moves the pointer to the corresponding 
position in the window. If the flag is cleared, refresh moves the cursor to the same position on the 
screen as the current pointer position in the window. The function call has the form: 


leaveok( win, state ) 


where win is a pointer to the window containing the flag to be set, and state is a Boolean value 
defining the state of the flag. If state is TRUE the flag is set; if FALSE, the flag is cleared. For 
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example, the function call 
leaveok(stdscr, TRUE); 
sets the cursor flag. 


The scrollok function sets or clears the scroll flag for the given window. If the flag is set, scrolling 
through the window is allowed. If the flag is clear, then no scrolling is allowed. The function call 
has the form: 


scrollok( win, state ) 


where win is a pointer to a window, and state is a Boolean value defining how the flag is to be set. 
If state is TRUE, the flag is set; if FALSE, the flag is cleared. The flag is initially clear, making 
scrolling illegal. 


The clearok function sets and clears the clear flag for a given screen. The function call has the 
form: 


clearok( win, state ) 


where win is a pointer to the desired screen, and state is a Boolean value. The function sets the 
flag if state is TRUE, and clears the flag if FALSE. For example, the function call 


clearok(stdscr, TRUE) 
sets the clear flag for the standard screen. 


When the clear flag is set, each refresh call to the given screen automatically clears the screen by 
passing a clear-screen sequence to the terminal. This sequence affects the terminal only; it does 
not change the contents of the screen. 


If clearok is used to set the clear flag for the current screen “‘curscr’’, each call to refresh 
automatically clears the screen, regardless of which window is given in the call. 


3.5.6 Scrolling a Window 


The scroll function scrolls the contents of a given window upward by one line. The function call 
has the form: 


scroll( win ) 


where win is a pointer to the window to be scrolled. The function should be used in special cases 
only. 


3.6 Combining Movement With Action 


Many screen operations move the current position of a given window before performing an action 
on the window. For convenience, you can combine a number of functions with the movement 
prefix. This combination has the form: 


mvfunc ( [ win, | y, x [, arg ] ... ) 


where func is the name of a function, win is a pointer to the window to be operated on (stdscr used 
if none is given), y is an integer value giving the line to move to, x is an integer value giving the 
column to move to, and arg is a required argument for the given function. If more than one 
argument is required they must be separated with commas (,). For example, the function call 


mvaddch(10, 5, ’X’); 


moves the position to (10,5) and adds the character “X”’. The operation is the same as moving the 
position with the move function and then adding a character with addch. 
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A complete list of the functions which may be used with the movement prefix is given in curses(S) 
in the XENIX Reference Manual. 


3.7 Controlling the Terminal 


The following sections explain how to set the terminal modes, how to move the cursor, and how to 
access other aspects of the terminal. These functions should only be used when using other screen 
processing functions. 


3.7.1 Setting a Terminal Mode 


The crmode, echo, nl, and raw functions set the terminal mode, causing subsequent input from 
the terminal’s keyboard to be processed accordingly. 


The crmode function sets the CBREAK mode for the terminal. The mode preserves the function 
of the signal keys, allowing allowing signals to be sent to a program from the keyboard, but 
disables the function of the editing keys. The function call has the form: 


crmode() 
No arguments are required. 


The echo function sets the ECHO mode for the terminal, causing each character typed at the 
keyboard to be displayed at the terminal screen. The function call has the form: 


-echo() 
No arguments are required. 


The n/ function sets a terminal to NEWLINE mode, causing all newline characters to be mapped 
to a corresponding newline and return character combination. The function call has the form: 


nl() 
No arguments are required. 


The raw function sets the RAW mode for the terminal, causing each character typed at the 
keyboard to be sent as direct input. The RAW mode disables the function of the editing and 
signal keys and disables the mapping of newline characters into newline and return 
combinations. The function call has the form: 


raw() 


No arguments are required. 


3.7.2 Clearing a Terminal Mode 


The nocrmode, noecho, nonl, and noraw functions clear the current terminal mode, allowing 
input to be processed according to a previous mode. 


The nocrmode function clears a terminal from the CBREAK mode. The function call has the 
form: 


nocrmode() 
No arguments are required. 


The noecho function clears a terminal from the ECHO mode. This mode prevents characters 
typed at the keyboard from being displayed on the terminal screen. The function call has the 
form: 


3-22 


Screen Processing 


noecho() 
No arguments are required. 


The nonl function clears a terminal from NEWLINE mode, causing newline characters to be 
mapped into themselves. This allows the screen processing functions to perform better 
optimization. The function call has the form: 


nonl() 
No arguments are required. 


The noraw function clears a terminal from RAW mode, restoring normal editing and signal 
generating function to the keyboard. The function call has the form: 


noraw() 


No arguments are required. 
3.7.3 Moving the Terminal’s Cursor 


The mvcur function moves the terminal’s cursor from one position to another in an optimal 
fashion. The function call has the form: 


mvcur ( last_y, last_x, new_y, new_x) 


where Jast_y and Jast_x are integer values giving the last line and column position of the cursor, 
and new_y and new _x are integer values giving the new line and column position of the cursor. 
For example, the function call 


mvcur(10, 5, 3, 0) 


moves the cursor from (10,5) to (3,0) on the terminal screen. 


Note 


The mvcur function should only be used in programs that do not use other screen 
processing functions. This means the function can be used to perform optimal cursor 
motion without the aid of the other functions. For programs that do use other 
functions, the move, wmove, refresh, and wrefresh functions must be used to move the 
cursor. 


3.7.4 Getting the Terminal Mode 


The gettmode function returns the current tty mode. The function call has the form: 
Ss = gettmode() 
where s is the variable to receive the status. 


The function is normally called by the initscr function. 
3.7.5 Saving and Restoring the Terminal Flags 


The savetty function saves the current terminal flags, and the resetty function restores the flags 
previously saved by the savetty function. These functions are performed automatically by initscr 
and endwin functions. They are not required when performing ordinary screen processing. 
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3.7.6 Setting a Terminal Type 


The stterm function sets the terminal type to the given type. The function call has the form: 
setterm( name ) 


where name is a pointer to a string containing the terminal type identifier. The function is 
normally called by the initscr function, but may be used in special cases. 


3.7.7 Reading the Terminal Name 


The /ongname function converts a given termcap identifier into the full name of the 
corresponding terminal. The function call has the form: 


longname( termbuf, name ) 


where termbuf is a pointer to the string containing the terminal type identifier, and name is a 
character pointer to the location to receive the long name. The terminal type identifier must exist 
in the /etc/termcap file. 


The function is typically used to get the full name of the terminal currently being used. Note that 
the current terminal’s identifier is stored in the variable “ttytype”, which may be used to receive a 
new name. 
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4.1 Introduction 


Character and string processing is an important part of many programs. Programs regularly 
assign, manipulate, and compare characters and strings in order to complete their tasks. For this 
reason, the standard library provides a variety of character and string processing functions. 
These functions give a convenient way to test, translate, assign, and compare characters and 
strings. 


To use the character functions in a program the file, ctype.h, which provides the definitions for 
special character macros, must be included in the program. The line 


#include <ctype.h> 
must appear at the beginning of the program. 


To use the string functions, no special action is required. These functions are defined in the 
standard C library and are read whenever you compile a C program. 


4.2 Using the Character Functions 


The character functions test and convert characters. Many character functions are defined as 
macros, and as such cannot be redefined or used as a target for a breakpoint when debugging. 


4.2.1 Testing for an ASCII Character 


The isascii function tests for characters in the ASCII character set, i.e., characters whose values 
range from 0 to 127. The function call has the form: 


isascii (c) 


where c is the character to be tested. The function returns a nonzero (true) value if the character 
is ASCII, otherwise it returns zero (false). For example, in the following program fragment 


66 99 


isascii determines whether or not the value in “‘c”’ read from the file given by “‘data”’ is in the 
acceptable ASCII range. 


FILE *data; 
int c; 


c = fgetc(data); 
if (tisascii(c)) 
notext(); 


In this example, a function named notext is called if the character is not in range. 


4.2.2 Converting to ASCII Characters 


The toascii function converts non-ASCII characters to ASCII. The function call has the form: 
c = toascii (/) 


where c is the variable to receive the character, and i is the value to be changed. The function 
creates an ASCII character by truncating all but the low order 7 bits of the non-ASCII value. If 
the i value is already an ASCII character, no change takes place. For example, the function call 


ascil = toascii(160) 


converts value 160 to 32, the ASCII value of the space character. 
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The function is typically used to prepare non-ASCII characters for display at the standard 
output. For example, in the following program fragment toascii converts each character read 
from the file given by “oddstream”’. 


FILE *oddstrm; 


int c; 


c = toascii( getc( oddstrm ) ); 
if ( isprint(c) | isspace(c) ) 
putchar(c); 


If the resulting character is printable or is whitespace, it is written to the standard output. 
4.2.3 Testing for Alphanumerics 


The isalnum function tests for letters and decimal digits, i.e., the alphanumeric characters. The 
function call has the form: 


isalnum (c) 


where c is the character to test. The function returns a nonzero (true) value if the character is an 
alphanumeric, otherwise it returns zero (false). For example, the function call 


isalnum(’1’) 
returns a nonzero value, but the call 
isalnum(’>’) 


returns zero. 
4.2.4 Testing for a Letter 


The isalpha function tests for uppercase or lowercase letters, i.e., alphabetic characters. The 
function call has the form: 


isalpha (c) 


where c is the character to be tested. The function returns a nonzero (true) value if the character 
is a letter, otherwise it returns zero. For example, the function call 


isalpha(’a’) 
returns a nonzero value, but the call 
isalpha(’1’) 


returns zero. 
4.2.5 Testing for Control Characters 


The iscntrl function test for control characters, i.e., characters whose ASCII values are in the 
range 0 to 31 oris 127. The function call has the form: 


iscntrl (c) 


where cis the character to be tested. The function returns a nonzero (true) value if the character 
is a control character, otherwise it returns zero (false). For example, in the program fragment 
iscntrl determines whether or not the character in “c” read from the file given by “‘infile” is a 
control character. 
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FILE *infile, *outfile; 
int c; 


c = fgetc(infile); 
if ( 'iscntrl(c) ) 
fputc( c, outfile ); 


The fputc function is ignored if the character is a control character. 


4.2.6 Testing for a Decimal Digit 


The isdigit function tests for decimal digits. The function call has the form: 
isdigit (c) 
where c is the character to be tested. The function returns a nonzero value if the character is a 


digit, otherwise it returns zero. For example, in the following program fragment each new 
character in “‘c” is added to the running total if the character is a digit. 


FILE *infile; 


int c, num; 


while ( isdigit( c=getc(infile) ) ) 
num = num*10 + c—48; 


4.2.7 Testing for a Hexadecimal Digit 


The isxdigit function tests for a hexadecimal digit, that is, a character that is either a decimal 
digit or an uppercase or lowercase letter in the range A to F. The function call has the form: 


isxdigit (c) 


where c is the character to be tested. The function returns a nonzero value if the character is a 
digit, otherwise it returns zero. For example, in the following program fragment isxdigit tests 
whether a hexadecimal digit is read from the standard input. 


int C; 
c = getchar(); 


if ( isxdigit(c) ) 
hexmode(); 


In this example, a function named hexmode is called if a hexadecimal digit is read. 


4.2.8 Testing for Printable Characters 
The isprint function tests for printable characters, i.e., characters whose ASCII values range 
from 32 to 126. The function call has the form: 

isprint (c) 


where c is the character to be tested. The function returns a nonzero value if the character is 
printable, otherwise it returns zero. 


4.2.9 Testing for Punctuation 


The ispunct function tests for punctuation characters, i.e., characters that are neither control 
characters nor alphanumeric characters. The function call has the form: 
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ispunct (c) 


where c is the character to be tested. The function returns a nonzero function if the character is a 
punctuation character, otherwise it returns zero. 


4.2.10 Testing for Whitespace 


The isspace function tests for whitespace characters, i.e, the space, horizontal tab, vertical tab, 
carriage return, formfeed, and newline characters. The function call has the form: 


isspace (c) 


where c is the character to be tested. The function returns a nonzero value is the character is a 
whitespace character, otherwise it returns zero. 


4.2.11 Testing for Case in Letters 


The isupper and islower functions test for uppercase and lowercase letters, respectively. The 
function calls have the form: 


isupper (c) 
and 
islower (c) 


where c is the character to be tested. The function returns a nonzero value if the character is the 
proper case, otherwise it returns zero. For example, the function call 


isupper(’b’) 
returns zero (false), but the call 
islower(’b’) 


returns a nonzero (true) value. 
4.2.12 Converting the Case of a Letter 


The tolower and toupper functions convert the case of a given letter. The function calls have the 
form: 


c = tolower (/) 
and 
c = toupper (Z) 


where c is the variable to receive the converted letter, and 7 is the letter to be converted. For 
example, the function call 


lower = tolower(’B’) 

converts “B”’ to “b”’ and assigns it to the variable “lower’’, and the call 
upper = toupper(’b’) 

converts ‘“‘b” to ““B”’ and assigns it to the variable “upper”’. 


The tolower function returns the character unchanged if it is not an uppercase letter. Similarly, 
the toupper function returns the character unchanged if it is not a lowercase letter. 


These functions are typically used to make the case of the characters read from a file or standard 
input consistent. For example, in the following statement tolower changes the character read 
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from the standard input to lowercase before it is compared. 


if ( tolower( getchar() ) != ’y’) 
exit(0); 


This conversion allows the user to type either “Y” or “y” to prevent the statement from executing 
the exit function. 


4.3 Using the String Functions 


The string functions concatenate, compare, copy, and count the number of characters in a string. 
Two special string functions, sscanf and sprintf, let a program read from and write to a string in 
the same way the standard input and output can be read and written. These functions are 
convenient when reading or writing whole lines containicg values of several different formats. 


Many string functions have two forms: a form that manipulates all characters in the string and 
one that manipulates a given number of characters. This gives programs very fine control over all 
or parts of strings. 


4.3.1 Concatenating Strings 


The strcat function concatenates two strings by appending the characters of one string to the end 
of another. The function call has the form: 


strcat (dst, src) 


where dst is a pointer to the string to receive the new characters, and src is a pointer to the string 
containing the new characters. The function appends the new characters in the same order as 
they appear in src, then appends a null character (\0) to the last character in the new string. The 
function always returns the pointer dst. 


The function is typically used to build a string such as a full pathname from two smaller strings. 
For example, in the following program fragment strcat concatenates the string “temp” to the 
contents of the character array “dir’’. 


char dir[MAX] = "/usr/"; 


strcat(dir, "temp"); 
4.3.2 Comparing Strings 


The strcmp function compares the characters in one string to those in another and returns an 
integer value showing the result of the comparison. The function call has the form: 


strcmp (s/, s2) 


where s/ and s2 are the pointers to the strings to be compared. The function returns zero if the 
strings are equal (i.e., have the same characters in the same order). If the strings are not equal, 
the function returns the difference between the ASCII values of the first unequal pair of 
characters. The value of the second string character is always subtracted from the first. For 
example, the function call 


stremp("Character A", "Character A"); 
returns zero since the strings are identical in every way, but the function call 
strcmp("Character A", "Character B"); 


returns —1 since the ASCII value of ““B”’ is one greater than “A”’. 
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Note that the function continues to compare characters until a mismatch is found. If one string is 
shorter than the other, the function usually stops at the end of the shorter string. For example, the 
function call 


stremp("Character A", "Character ") 


returns 65, that is, the difference between the null character at the end of the second string and 
the “A” in the first string. 


4.3.3 Copying a String 


The strcpy function copies a given string to a given location. The function call has the form: 
strepy (dst, src) 


where src is a pointer to the string to be copied, and dst is a pointer to the location to receive the 
string. The function copies all characters in the source string src to the dst and appends a null 
character (\0) to the end of the new string. If dst contained a string before the copy, that string is 
destroyed. The function always returns the pointer to the new string. 


For example, in the program fragment strcpy copies the string “not available” to the location 
given by “name’”’. 


char na[] = "not available"; 
char name[20]; 
strcpy( name, na ); 


Note that the location to receive a string must be large enough to contain the string. The function 
cannot detect overflow. 


4.3.4 Getting a String’s Length 


The str/en function returns the number of character contained ina given string. The function call 
has the form: 


strlen (s) 


where s is a pointer to a string. The count includes all characters up to, but not including, the first 
null character. The return value is always an integer. 


In the following program fragment, str/en is used to determine whether or not the contents of 
‘“inname’” are short enough to be stored in “name”. 


char *inname; 
char name[MAX]; 


if ( strlen(inname) < MAX ) 
strcpy( name, inname); 


4.3.5 Concatenating Characters to a String 


The strncat function appends one or more characters to the end of a given string. The function 
call has the form: 


strncat (dst, src, n) 


where dst is a pointer to the string to receive the new characters, src is a pointer to the string 
containing the new characters, and n is an integer value giving the number of characters to be 
concatenated. The function appends the given number of character to the end of the dst string, 
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then returns the pointer dst. 


In the following program fragment, strncat copies the first three characters in “letter” to the end 
of “‘cover”’. 


char cover[] = "cover"; 
char letter[] = "letter’; 
strncat( cover, letter, 3); 


This example creates the new string “‘coverlet”’ in “‘cover”’. 
4.3.6 Comparing Characters in Strings 


The strncmp function compares one or more pairs of characters in two given strings and returns 
an integer value which gives the result of the comparison. The function call has the form: 


strncmp (s/, s2, n) 


where s/ and s2 are pointers to the strings to be compared, and n is an integer value giving the 
number of characters to compare. The function returns zero if the first n characters are identical. 
Otherwise, the function returns the difference between the ASCII values of the first unequal pair 
of characters. The function generates the difference by subtracting the second string character 
from the first. 


For example, the function call 
strncmp("Character A", "Character B", 5) 

returns zero because the first five characters are identical, but the function call 
strncmp("Character A", "Character B", 11) 

returns —1 because the value of ““B” is one greater than “A”’. 


Note that the function continues to compare characters until a mismatch or the end of a string is 
found. 


4.3.7 Copying Characters to a String 


The strncpy function copies a given number of characters to a given string. The function call has 
the form: 


strncpy (dst, src, n) 


where dst is a pointer to the string to receive the characters, src is a pointer to the string 
containing the characters, and n is an integer value giving the number of characters to be copied. 
The function copies either the first n characters in src to dst, or if src has fewer than n characters, 
copies all characters up to the first null character. The function always returns the pointer dst. 


In the following program fragment, strncpy copies the first three characters in “date” to “day”. 


char buf [MAX]; 
char date [29] = {"Fri Dec 29 09:35:44 EDT 1982"}; 
char *day = buf; 


strncpy( day, date, 3); 


In this example, “day” receives the string ‘Fri’. 
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4.3.8 Reading Values from a String 


The sscanf function reads one or more values from a given character string and stores the values 
at a given memory location. The function is similar to the scanf function which reads values from 
the standard input. The function call has the form: 


sscanf (s, format, argptr ...) 


where s is a pointer to the string to be read, format is a pointer to the string defining the format of 
the values to be read, and argptr is a pointer to the variable that is to receive the values read. If 
more than one argptr is given, they must be separated with commas. The format string may 
contain the same formats as given for scanf (see scanf(S) in the XENIX Reference Manual). The 
function always returns the number of values read. 


The function is typically used to read values from a string containing several values of different 
formats, or to read values from a program’s own input buffer. For example, in the following 
program fragment sscanf reads two values from the string pointed to by “datastr’’. 


char datestr[] = {"THU MAR 29 11:04:40 PST 1983}: 

char day[4], month[4], time[9], tz[4]; 

int date, year; 

sscanf(datestr,"%os Ys Yod Ys Yos Yod", day, month, &date, time, tz, &year); 


The first string ("THU") will be copied to the area pointed to by day. The next string ("MAR") 
will be copied to month. The next field, 29, will be treated as a decimal number and its value 
copied to the variable date. 


4.3.9 Writing Values to a String 


The sprintf function writes one or more values to a given string. The function call has the form: 
sprintf (s, format [, arg] ...) 


where s is a pointer to the string to receive the value, format is a pointer to a string which defines 
the format of the values to be written, and arg is the variable or value to be written. If more than 
one arg is given, they must be separated by commas (,). The format string may contain the same 
formats as given for printf (see printf(S) in the XENIX Reference Manual). After all values are 
written to the string, the function adds a null character (\0) to the end of the string. The function 
normally returns zero, but will return a nonzero value if an error is encountered. 


The function is typically used to build a large string from several values of different format. For 
example, in the following program fragment sprintf writes three values to the string pointed to by 
“cmd’’. 


char cmd[100]; 
char *doc = "/usr/src/cmd/cp.c" 
int width = 50; 
int length = 60; 


sprintf(cmd,"pr -w%d -1%d %s\n",width,length,doc); 
system(cmd); 


In this example, the string created by sprintfis used in a call to the system function. The first two 
values are the decimal numbers given by “width” and “length”. The last value is a string (a 
filename) and is pointed to by doc. The final string has the form: 


pr -w50 -160 /usr/src/cmd/cp.c 


Note that the string to receive the values must have sufficient length to store those values. The 
function cannot check for overflow. 
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5.1 Introduction 


This chapter describes the process control functions of the standard C library. The functions let a 
program call other programs, using a method similar to calling functions. 


There are a variety of process control functions. The system and exit functions provide the 
highest level of execution control and are used by most programs that need a straightforward way 
to call another program or terminate the current one. The execl, execv, fork, and wait functions 
provide low-level control of execution and are for those programs which must have very fine 
control over their own execution and the execution of other programs. Other process control 
functions such as abort and exec are described in detail in section S of the XENIX Reference 
Manual. 


The process control functions are a part of the standard C library. Since this library is 
automatically read when compiling a C program, no special library argument is required when 
invoking the compiler. 


5.2 Using Processes 


“Process” is the term used to describe a program executed by the XENIX system. A process 
consists of instructions and data, and a table of information about the program, such as its 
allocated memory, open files, and current execution status. 


You create a process whenever you invoke a program through a shell. The system assigns a 
unique process ID to a program when it is invoked, and uses this ID to control and manage the 
program. The unique IDs are needed in a system running several processes at the same time. 


You can also create a process by directing a program to call another program. This causes the 
system to perform the same functions as when it invokes a program through a shell. In fact, these 
two methods are actually the same method — invoking a program through a shell is nothing more 
than directing a program (the shell) to call another program. 


The system handles all processes in essentially the same way, so the sections that follow should 
give you valuable information for writing your own programs and an insight into the XENIX 
system itself. 


5.3 Calling a Program 


The system function calls the given program, executes it, and then returns control to the original 
program. The function call has the form: 


system (command-line) 


where command-line is a pointer to a string containing a shell command line. The command line 
must be exactly as it would be typed at the terminal, that is, it must begin with the program name 
followed by any required or optional arguments. For example, the call 


system("date"); 


causes the system to execute the date command, which displays the current time and date at the 
standard output. The call 


system("cat >response"); 


causes the system to execute the cat command. In this case, the standard output is redirected to 
the file response, so the command reads from the standard input and copies this input to the file 
response. 


The system function is typically used in the same way as a function call to execute a program and 
return to the original program. For example, in the following program fragment system calls a 
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program whose nameis given in the string ““cmd”’. 


char *name, *cmd; 


printf("Enter filename: "); 
scanf("%s", name); 
sprintf(cmd, "cat %s ", name); 
system(cmd); 


Note that the string in ““cmd” is built using the sprintf function and contains the program name 
cat and an argument (the filename read by scanf). The effect is to execute the cat command with 
the given filename. 


When using the system function, it is important to remember that buffered input and output 
functions, such as getc and putc, do not change the contents of their buffer until it is ready to be 
read or flushed. If a program uses one of these functions, then executes a command with the 
system function, that command may read or write data not intended for its use. To avoid this 
problem, the program should clear all buffered input and output before making a call to the 
system function. You can do this for output with the flush function, and for input with the setbuf 
function described in the section “Using More Stream Functions” in Chapter 2. 


5.4 Stopping a Program 


The exit function stops the execution of a program by returning control to the system. The 
function call has the form: 


exit (status) 
where Status is the integer value to be sent to the system as the termination status. 


The function is typically used to terminate a program before its normal end, such as after a 
serious error. For example, in the following program fragment exit stops the program and sends 
the integer value “‘2”’ to the system if the fopen function returns the null pointer value NULL. 


FILE *ttyout; 
if ( fopen(ttyout,"r") == NULL ) 
exit(2); 


Note that the exit function automatically closes each open file in the program before returning to 
the system. This means no explicit calls to the fclose or close functions are required before an 
exit. 


5.5 Overlaying a Program 


The execl and execy functions cause the system to overlay the calling program with the given one, 
allowing the calling program to terminate while the new program continues execution. 


The exec/ function call has the form: 
execl (pathname, command-name, argptr ...) 


where pathname is a pointer to a string containing the full pathname of the command you want to 
execute, command-name is a pointer to a string containing the name of the program you want to 
execute, and argpir is one or more pointers to strings which contain the program arguments. 
Each argptr must be separated from any other argument by a comma. The last argptr in the list 
must be the null pointer value NULL. For example, in the call 


execl("/bin/date", "date", NULL): 


the date command, whose full pathname is “/bin/date’’, takes no arguments, and in the call 
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execl("/bin/cat", "cat", filel, file2, NULL); 


the cat command, whose full pathname is “/bin/cat”’, takes the pointers “‘filel” and “‘file2” as 
arguments. 


The execyv function call has the form: 
execv (pathname, ptr); 


where pathname is the full pathname of the program you want to execute, and pir is pointer to an 
array of pointers. Each element in the array must point to a string. The array may have any 
number of elements, but the first element must point to a string containing the program name, 
and the last must be the null pointer, NULL. 


The exec! and execv functions are typically used in programs that execute in two or more phases 
and communicate through temporary files (for example a two-pass compiler). The first part of 
such a program can call the second part by giving the name of the second part and the appropriate 
arguments. For example, the following program fragment checks the status of “‘errflag”’, then 
either overlays the current program with the program pass2, or displays an error message and 
quits. 


char *tmpfile; 
int errflag; 


if (errflag == 0) 
execl("/usr/bin/pass2", "pass2", tmpfile, NULL); 
else { 
fprintf(stderr, "Error %d: Quitting", errflag); 
exit(2); 


The execv function is typically used to pass arguments to a program when the precise number of 
arguments is not known beforehand. For example, the following program fragment reads 
arguments from the command line (beginning with the third one), copies the pointer of each toan 
element in “‘cmd’’, sets the last element in “‘“cmd”’ to NULL, and executes the cat command. 


char *cmd{]; 


cmd[0] = "cat"; 

for (i=3; i<argce; i++) 
cmd[i] = argv[i]; 

cmd[i] = NULL; 


execv("/bin/cat", cmd); 
The exec! and execv functions return control to the original program only if there is an error in 
finding the given program (e.g., a misspelled pathname or no execute permission). This allows 
the original program to check for errors and display an error message if necessary. For example, 
the following program fragment searches for the program display in the /usr/bin directory. 

execl("/usr/bin/display", "display", NULL); 

fprintf(stderr, "Can’t execute “display’ \n"); 
If the program display is not found or lacks the necessary permissions, the original program 
resumes control and displays an error message. 


Note that the exec/ and execv functions will not expand metacharacters (e.g., <<, >, *, ?, and [ ]) 
given in the argument list. If a program needs these features, it can use execl or execy to calla 
shell as described in the next section. 
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5.6 Executing a Program Through a Shell 


One drawback of the exec/ and execv functions is that they do not provide the metacharacter 
features of a shell. One way to overcome this problem is to use exec/ to execute a shell and let the 
shell execute the command you want. 


The function call has the form: 
execl ("/bin/sh","sh","—c", command-line, NULL); 


where command-line is a pointer to the string containing the command line needed to execute the 
program. The string must be exactly as it would appear if typed at the terminal. 


For example, a program can execute the command 
Cab c 

(which contains the metacharacter * ) with the call 
execi("/ bin/sh’, “sh”, "—c""-, "eat. *.c’, NULL); 


In this example, the full pathname /bin/sh and command name sh start the shell. The argument 
*“—c”? causes the shell to treat the argument “‘cat *.c” as a whole command line. The shell 
expands the metacharacter and displays all files which end with .c, something that the cat 
command cannot do by itself. 


5.7 Duplicating a Process 


The fork function splits an executing program into two independent and fully-functioning 
processes. The function call has the form: 


fork () 
No arguments are required. 


The function is typically used to make multiple copies of any program that must take divergent 
actions as a part of its normal operation, e.g., a program that must use the exec/ function yet still 
continue to execute. The original program, called the “parent” process, continues to execute 
normally, just as it would after any other function call. The new process, called the “child” 
process, starts its execution at the same point, that is, just after the fork call. (The child never 
goes back to the beginning of the program to start execution.) The two processes are in effect 
synchronized, and continue to execute as independent programs. 


The fork function returns a different value to each process. To the parent process, the function 
returns the process ID of the child. The process ID is always a positive integer and is always 
different than the parent’s ID. To the child, the function returns 0. All other variables and values 
remain exactly as they were in the parent. 


The return value is typically used to determine which steps the child and parent should take next. 
For example, in the program segment 


char *cmd; 
if (fork() == 0) 
execl("/bin/sh", "sh", "—c", cmd, NULL); 


The child’s return value, 0, causes the expression “‘fork() == 0’, to be true, and therefore the 
execl function is called. The parent’s return value, on the other hand, causes the expression to be 
false, and the function call is skipped. Executing the exec! function causes the child to be 
overlayed by the program given by “command’”’. This does not affect the parent. 


If fork encounters an error and cannot create a child, it will return the value —1. It is a good idea 
to check for this value after each call. 
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5.8 Waiting for a Process 


The wait function causes a parent process to wait until its child processes have completed their 
execution before continuing its own execution. The function call has the form: 


wait (ptr) 


where pir is a pointer to an integer variable. It receives the termination status of the child from 
both the system and the child itself. The function normally returns the process ID of the 
terminated child, so the parent may check it against the value returned by fork. 


The function is typically used to synchronize the execution of a parent and its child, and is 
especially useful if the parent and child processes access the same files. For example, the 
following program fragment causes the parent to wait while the program named by “pathname” 
(which has overlaid the child process) finishes its execution. 


int status; 
char *pathname; 
char *cmd[]; 


if (fork() == 0) 
execv(pathname, cmd); 
wait( &status); 


The wait function always copies a status value to its argument. The status value is actually two 8 
bit values combined into one. The low-order 8 bits is the termination status of the child as defined 
by the system. This status is zero for normal termination and nonzero for other kinds of 
termination, such as termination by an interrupt, quit, or hangup signal (see signal(S) in the 
XENIX Reference Manual for a description of the various kinds of termination). The next 8 bits 
is the termination status of the child as defined by its own call to exit. If the child did not 
explicitly call the function, the status is zero. 


5.9 Inheriting Open Files 


Any program called by another program or created as a child process to aprogram automatically 
inherits the original program’s open files and standard input, output, and error files. This means 
if the file was open in the original program, it will be open in the new program or process. 


A new program also inherits the contents of the input and output buffers used by the open files of 
the original program. To prevent toa new program or process from reading or writing data that is 
not intended for its use, these buffers should be flushed before calling the program or creating the 
new process. A program can flush an output buffer with the ffush function, and an input buffer 
with setbuf. 


5.10 Program Example 


This section shows how to use the process control functions to control a simple process. The 
following program starts a shell on the terminal given in the command line. The terminal is 
assumed to be connected to the system through a line that has not been enabled for multiuser 
operation. 
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#include <stdio.h> 


main(argc, argv) 
int argc; 
char *argv[]; 


int status, pid, w; 


if (arge < 2) { 
fprintf(stderr,"No tty given.0); 
exit(1); 


pid = fork(); 

if (pid <0 ){ 
fprintf(stderr, "Can’t Fork'!\n"); 
exit(2); 


if (fork() == 0) { 
if (freopen(argv[1],"r",stdin) == NULL) 
exit(2); 
if (freopen(argv[1],"w",stdout) == NULL) 
exit(2); 
if (freopen(argv[1],"w",stderr) == NULL) 
exit(2); 
execl("/bin/sh","sh",NULL); 
} 
do { 
WwW = wait( &status); 
}while (w != pid && w != —1); 
if (status > > 8 == 2) 
fprintf(stderr, "Bad tty name: %s, argv[1]); 


In this example, the fork function creates a duplicate copy of the program. The child changes the 
standard input, output, and error files to the new terminal by closing and reopening them with the 
freopen function. The terminal name pointed to by “argv” must be the name of the device special 
file associated with the terminal, e.g., ““/dev/tty03”. The exec/ function then calls the shell 
which uses the new terminal as its standard input, output, and error files. 


The parent process waits for the child to terminate. The exit function terminates the process if an 
error occurs when reopening the standard files. Otherwise, the process continues until the 
CNTRL-D key is pressed at the new terminal. 
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6.1 Introduction 


A pipe is an artifical file that a program may create and use to pass information to other 
programs. A pipe is similar to a file in that it has a file pointer and/or a file descriptor and can be 
read from or written to using the input and output functions of the standard library. Unlike a file, 
a pipe does not represent a specific file or device. Instead a pipe represents temporary storage in 
memory that is independent of the program’s own memory and is controlled entirely by the 
system. 


Pipes are chiefly used to pass information between programs, just as the shell pipe symbol (|), is 
used to pass the output of one program to the input of another. This eliminates the need to create 
temporary files to pass information to other programs. A pipe can also be used as a temporary 
storage place for a single program. A program can write to the pipe, then read that information 
back at a later time. 


The standard library provides several pipe functions. The popen and pclose functions control 
both a pipe and a process. The popen opens a pipe and creates a new process at the same time, 
making the new pipe the standard input or output of the new process. The pclose function closes 
the pipe and waits for termination of the corresponding process. The pipe function, on the other 
hand, gives low-level access to a pipe. The function is similar to the open function, but opens the 
pipe for both reading and writing, returning two file descriptors instead of one. The program can 
either use both sides of the pipe or close the one it does not need. The low-level input and output 
functions read and write can be used to read from and write to a pipe. Pipe file descriptors are 
used in the same way as other file descriptors. 


6.2 Opening a Pipe to a New Process 


The popen function creates a new process and then opens a pipe to the standard input or output 
file of that new process. The function call has the form: 


popen (command, type) 


where command is a pointer to a string that contains a shell command line, and type is a pointer to 
the string which defines whether the pipe is to be opened for reading or writing by the original 
process. It may be “‘r’”’ for reading or “w” for writing. The function normally returns the file 
pointer to the open pipe, but will return the null pointer value NULL if an error is encountered. 


The function is typically used in programs that need to call another program and pass substantial 
amounts of data to that program. For example, in the following program fragment popen creates 
a new process for the cat command and opens a pipe for writing. 


FILE *pstrm; 


pstrm = popen("cat >response","w"); 


The new pipe given by “pstrm” links the standard input of the command with the program. Data 
written to the pipe will be used as input by the cat command. 


6.3 Reading and Writing to a Process 


The fscanf, fprintf, and other stream functions may be used to read from or write to a pipe 
opened by the popen function. These functions have the same form as described in Chapter 2. 


The fscanf function can be used to read from a pipe opened for reading. For example, in the 
following program fragment fscanf reads from the pipe given by pstrm. 


6-1 


XENIX Programmer’s Reference 


FILE *pstrm; 
char name[20]; 
int number; 


pstrm = popen("cat","r"); 
fscanf(pstrm, "%s %d", name, &number); 


This pipe is connected to the standard output of the cat command, so fscanf reads the first name 
and number written by cat to its standard output. 


The fprintf function can be used to read from a pipe opened for writing. For example, in the 
following program fragment fprintf writes the string pointed to by “buf” to the pipe given by 
““pstrm”’. 


FILE *pstrm; 

char buf[MAX]; 

pstrm = popen("wc","w"); 
fprintf(pstrm,"%s", buf) 


This pipe is connected to the standard input of the wc command, so the command reads and 
counts the contents of “buf”. 


6.4 Closing a Pipe 


The pclose function closes the pipe opened by the popen function. The function call has the form: 
pclose (stream) 


where stream is the file pointer of the pipe to be closed. The function normally returns the exit 
status of the command that was issued as the first argument of its corresponding popen, but will 
return the value —1 if the pipe was not opened by popen. 


For example, in the following program fragment pclose closes the pipe given by “‘pstrm”’ if the 
end-of-file value EOF has been found in the pipe. 


FILE *pstrm; 


if (feof(pstrm)) 
pclose (pstrm); 


6.5 Opening a Low-Level Pipe 


The pipe function opens a pipe for both reading and writing. The function call has the form: 


pipe (fd) 


where fd is a pointer to a two-element array. It must have int type. Each element receives one file 
descriptor. The first element receives the file descriptor for the reading side of the pipe, and the 
other element receives the file descriptor for the writing side. The function normally returns 0, 
but will return the value —1 if an error is encountered. For example, in the following program 
fragment pipe creates two file descriptors if no error is encountered. 


int chan[2]; 
if (pipe(chan) == —1) 
exit(2); 


The array element “‘chan[0]” receives the file descriptor for the reading side of the pipe, and 
““chan[1]” receives it for the writing side. 
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The function is typically used to open a pipe in preparation for linking it to a child process. For 
example, in the following program fragment pipe causes the program to create a child process if it 
successfully creates a pipe. 


int fd[2]; 
if (pipe(fd) != -1) 


if ( fork) == 0 ) 
close(fd[1]); 


Note that the child process closes the writing side of the pipe. The parent can now pass data to the 
child by writing to the pipe; the child can retrieve the data by reading the pipe. 


6.6 Reading and Writing to a Low-Level Pipe 


The read and write input and output functions can be used to read and write characters to a low- 
level pipe. These functions have the same form and operation described in Chapter 2. 


The read function can be used to read from the read side of an open pipe. For example, in the 
following program fragment read reads MAX characters from the read side of the pipe given by 
“chan”’. 


int chan[2]; 
char buf[MAX]; 
int number; 


number = read(chan[0], buf, MAX); 


In this example, read stores the characters in the array “buf”. 


Note that unless the end-of-file character is encountered, a read call waits for the given number 
of characters to be read before returning. 


The write function can be used to write to the write side of a pipe. For example, in the following 
program fragment write writes MAX characters from the character array “buf” to the writing 
side of the pipe given by “‘chan”’. 


int chan[2]; 
char buf[MAX]; 
int number; 


pipe(chan); 
number = write(chan[1], input, 512); 


If the write function finds that a pipe is too full, it waits until some characters have been read 
before completing its operation. 


6.7 Closing a Low-Level Pipe 


The close function can be used to close the reading or the writing side of a pipe. The function has 
the same form and operation as described in Chapter 2. For example, the function call 


close(chan[0]) 

closes the reading side of the pipe given by “chan’’, and the call 
close(chan[1]) 

closes the writing side. 


The system copies the end-of-file value EOF to a pipe when the process that made the original pipe 
and every process created or called by that process has closed the writing side of the pipe. This 
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means, for example, that if a parent process is sending data toa child process through a pipe and 
closes the pipe to signal the end of the file, the child process will not receive the end-of-file value 
unless it has already closed its own write side of the pipe. 


6.8 Program Examples 


This section shows how to use the process control functions with the low-level pipe function to 
create functions similar to the popen and pclose functions. 


The first example is a modified version of the popen function. The modified function identifies the 
new pipe with a file descriptor rather than a file pointer. It also requires a “mode” argument 
rather thana “type” argument, where the mode is 0 for reading or 1 for writing. 


#include <stdio.h> 


#define READ 0 

#define WRITE1 

#define tst(a, b) (mode == READ ? (b): (a)) 
static int popen_pid; 


popen(cmd, mode) 
char *cmd; 
int mode; 
{ 
int p[2]; 


if (pipe(p) < 0) 
return(NULL); 


if ((popen_pid = fork()) == 0) { 
close(tst(p[ WRITE], p[READ])); 
close(tst(0, 1)); 
dup(tst(p[READ], p[WRITE])); 
close(tst(p[ READ], p[WRITE])); 
execl("/bin/sh", "sh", "-c", cmd, 0); 
exit(1); /* sh cannot be found */ 

} 

if (popen pid == —1) 
return(—1); 


close(tst(p[ READ], p[WRITE])); 
return(tst(p[ WRITE], p[READ])); 
} 


The function creates a pipe with the pipe function first. It then uses the fork function to create 
two copies of the original process. Each process has its own copy of the pipe. The child process 
decides whether it is supposed to read or write through the pipe, then closes the other side of the 
pipe and uses exec/ to create the new process and execute the desired program. The parent, on the 
other hand, closes the side of the pipe it does not use. 


The sequence of close functions in the child process is a trick used to link the standard input or 
output of the child process to the pipe. The first close determines which side of the pipe should be 
closed and closes it. If “mode” is WRITE, the writing side is closed; if READ the reading side is 
closed. The second close closes the standard input or output depending on the mode. If the mode 
is WRITE, the input is closed; if READ, the output is closed. The dup function creates a duplicate 
of the side of the pipe still open. Since the standard input or output was closed immediately 
before this call, this duplicate receives the same file descriptor as the standard file. The system 
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always chooses the lowest available file descriptor for a newly opened file. Since the duplicate 
pipe has the same file descriptor as the standard file it becomes the standard input or output file 
for the process. Finally, the last close closes the original pipe, leaving only the duplicate. 


The following example is a modified version of the pclose function. The modified version requires 
a file descriptor as an argument rather than a file pointer. 


#include <signal.h> 


pclose(fd) /* close pipe fd'* / 

int fd; 

{ 
int r, status; 
int (*hstat)(), (*istat)(), (*qstat)(; 
extern int popen_ pid; 


close(fd); 


istat = signal(SIGINT, SIG _ IGN); 
qstat = signal(SIGQUIT, SIG_IGN); 
hstat = signal(SIGHUP, SIG_IGN); 


do 
r = wait(&status); 
while (r != popen pid && r != —1); 


if (r == —1) 
status = —1; 


signal(SIGINT, istat); 
signal(SIGQUIT, qstat); 
signal(SIGHUP, hstat); 


return(status); 


} 


The function closes the pipe first. It then uses a while statement to wait for the child process given 
by “popen_pid”’. If other child processes terminate while it waits, it ignores them and continues 
to wait for the given process. It stops waiting as soon as the given process terminates or if no child 
process exists. The function returns the termination status of the child, or the value —1 if there 
was anerror. 


The signal function calls used in this example ensure that no interrupts interfere with the waiting 
process. The first set of functions causes the process to ignore the interrupt, quit, and hang up 
signals. The last set restores the signals to their original status. The signal function is described 
in detail in the next chapter, “Using Signals”’. 


Note that both example functions use the external variable “‘popen_pid”’ to store the process ID of 
the child process. If more than one pipe is to be opened, the “‘popen_pid’’ value must be saved in 
another variable before each call to popen, and this value must be restored before calling pclose 
to close the pipe. The functions can be modified to support more than one pipe by changing the 
““popen_pid” variable to an array indexed by file descriptor. 
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7.1 Introduction 


This chapter explains how to use C library functions to process signals sent to a program by the 
XENIX system. A signal is the system’s response to an unusual condition that occurs during 
execution of a program such as a user pressing the INTERRUPT key or the system detecting an 
illegal operation. A signal interrupts normal execution of the program and initiates an action 
such as terminating the program or displaying an error message. 


The signal function of the standard C library lets a program define the action of a signal. The 
function can be used to disable a signal to prevent it from affecting the program. It can also be 
used to give a signal a user-defined action. 


The signal function is often used with the setjmp and /ongjmp functions to redefine and reshape 
the action of a signal. These functions allow programs to save and restore the execution state of a 
program, giving a program a means to jump from one state of execution to another without a 
complex assembly language interface. 


To use the signal function, you must add the line 
#include <signal.h> 


to the beginning of the program. The signal.h file defines the various manifest constants used as 
arguments by the function. To use the setjmp and /ongjmp functions you must add the line 


#include <setjmp.h> 


to the beginning of the program. The setjmp.h file contains the declaration for the type jmp_buf, 
a template for saving a program’s current execution state. 


7.2 Using the signal Function 


The signal function changes the action of a signal from its current action to a given action. The 
function has the form 
signal (sigtype, ptr) 


where sigtype is an integer or a mainfest constant that defines the signal to be changed, and ptr is 
a pointer to the function defining the new action or a manifest constant giving a predefined action. 
The function always returns a pointer value. This pointer defines the signal’s previous action and 
may be used in subsequent calls to restore the signal to its previous value. 


The ptr may be “SIG_IGN” to indicate no action (ignore the signal) or “SIG_DFL” to indicate 
the default action. The sigtype may be “SIGINT” for interrupt signal, caused by pressing the 
INTERRUPT key, “SIGQUIT” for quit signal, caused by pressing the QUIT key, or “SIGHUP” 
for hangup signal, caused by hanging up the line when connected to the system by modem. 
(Other constants for other signals are given in signal (S) in the XENIX Reference Manual.) 


For example, the function call 
signal(SIGINT, SIG_IGN) 


changes the action of the interrupt signal to no action. The signal will have no effect on the 
program. The default action is usually to terminate the program. 


The following sections show how to use the signal function to disable, change, and restore signals. 


7.2.1 Disabling a Signal 


You can disable a signal, i.e., prevent it from affecting a program, by using the “SIG_IGN” 
constant with signal. The function call has the form 


7-1 


XENIX Programmer’s Reference 


signal (sigtype, SIG_ IGN) 


where sigtype is the manifest constant of the signal you wish to disable. For example, the 
function call 


signal(SIGINT, SIG_IGN); 
disables the interrupt signal. 


The function call is typically used to prevent a signal from terminating a program executing in 
the background (e.g., a child process that is not using the terminal for input or output). The 
system passes signals generated from keystrokes at a terminal to all programs that have been 
invoked from that terminal. This means that pressing the INTERRUPT key to stop a program 
running in the foreground will also stop a program running in the background if it has not 
disabled that signal. For example, in the following program fragment signal is used to disable the 
interrupt signal for the child. 


#include <signal.h> 


main () 


if ( fork() == 0) { 
signal(SIGINT, SIG_IGN); 
/* Child process. */ 


} 


/? Parent process. */ 


} 


This call does not affect the parent process which continues to receive interrupts as before. Note 
that if the parent process is interrupted, the child process continues to execute until it reaches its 
normal end. 


7.2.2 Restoring a Signal’s Default Action 


You can restore a signal to its default action by using the “SIG_DFL” constant with signal. The 
function call has the form 


signal (sigtype, SIGDFL) 


where sigtype is the manifest constant defining the signal you wish to restore. For example, the 
function call 


signal (SIGINT, SIG_DFL) 
restores the interrupt signal to its default action. 


The function call is typically used to restore a signal after it has been temporarily disabled to keep 
it from interrupting critical operations. For example, in the following program fragment the 
second call to signal restores the signal to its default action. 
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#include <signal.h> 
Hinclude <stdio.h> 


main () 


int fd; 
char record[BUF], filename[MAX]; 


signal (SIGINT, SIG_IGN); 

fd = open(filename, 2); 

write(fd, record, BUF); 

signal (SIGINT, SIG_DFL); 
} 


In this example, the interrupt signal is ignored while a record is written to the file described by 
bik sia 


7.2.3 Catching a Signal 


You can catch a signal and define your own action for it by providing a function that defines the 
new action and giving the function as an argument to signal. The function call has the form 


signal (sigtype, newptr) 


where sigtype is the manifest constant defining the signal to be caught, and newpztr is a pointer to 
the function defining the new action. For example, the function call 


signal(SIGINT, catch) 
changes the action of the interrupt signal to the action defined by the function named catch. 


The function call is typically used to let a program do additional processing before terminating. 
In the following program fragment, the function catch defines the new action for the interrupt 
signal. 


#include <signal.h> 
main () 
int catch (); 


printf("Press INTERRUPT key to stop.0); 
signal (SIGINT, catch); 
while () { 

/* Body */ 


} 
catch () 
{ 


printf("Program terminated.\n"); 
exit(1); 


The catch function prints the message “Program terminated” before stopping the program with 
the exit function. 


A program may redefine the action of a signal at any time. Thus, many programs define different 
actions for different conditions. For example, in the following program fragment the action of the 
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interrupt signal depends on the return value of a function named keytest. 


#include <signal.h> 
main () 
int catch] (), catch2 (); 


if (keytest() == 1) 
signal(SIGINT, catch1); 
else 
signal(SIGINT, catch2); 


} 
Later the program may change the signal to the other action or even a third action. 


When using a function pointer in the signal call, you must make sure that the function name is 
defined before the call. In the program fragment shown above, catch! and catch2 are explicitly 
declared at the beginning of the main program function. Their formal definitions are assumed to 
appear after the signal call. 


7.2.4 Restoring a Signal 


You can restore a signal to its previous value by saving the return value of a signal call, then using 
this value in a subsequent call. The function call has the form: 

signal (sigtype, oldptr) 
where sigtype is the manifest constant defining the signal to be restored and o/dptr is the pointer 
value returned by a previous signal call. 


The function call is typically used to restore a signal when its previous action may be one of many 
possible actions. For example, in the following program fragment the previous action depends 
solely on the return value of a function keytest. 


#include <signal.h> 
main () 


int catch1(), catch2(); 
int (*savesig)(); 


if (keytest() == 1) 
signal(SIGINT, catch1); 
else 
signal(SIGINT, catch2); 


savesig = signal (SIGINT, SIG IGN); 
compute(); 
signal(SIGINT, savesig); 


} 


In this example, the old pointer is saved in the variable “‘savesig”. This value is restored after the 
function compute returns. 
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7.2.5 Program Example 


This section shows how to use the signal function to create a modifed version of the system 
function. In this version, system disables all interrupts in the parent process until the child 
process has completed its operation. It then restores the signals to their previous actions. 


#include <stdio.h> 
#include <signal.h> 


system(s) /* run command string s */ 
char *s; 
{ 

int status, pid, w; 

register int (*istat)(), (*qstat)(); 


if ((pid = fork()) == 0) { 
execi("/bin/sh";"sh', “—c",.S; NULL); 
exit(—127): 
} 
istat = signal(SIGINT, SIG_IGN); 
qstat = signal(SIGQUIT, SIG _ IGN); 
do 
w = wait(&status); 
while (w != pid & & w != —1); 
if (w == —1) 
status = —1; 
signal(SIGINT, istat); 
signal(SIGQUIT, qstat); 
return(status); 


} 


Note that the parent uses the while statement to wait until the child’s process ID “pid” is returned 
by wait. If wait returns the error code “—1” no more child processes are left, so the parent returns 
the error code as its own status. 


7.3 Controlling Execution With Signals 


Signals do not need to be used solely as a means of immediately terminating a program. Many 
signals can be redefined to delay their actions or even cause actions that terminate a portion of a 
program without terminating the entire program. The following sections describe ways that 
signals can be caught and used to provide control of a program. 


7.3.1 Delaying a Signal’s Action 


You can delay the action of a signal by catching the signal and redefining its action to be nothing 
more than setting a globally-defined flag. Such a signal does nothing to the current execution of 
the program. Instead, the program continues uninterrupted until it can test the flag to see if a 
signal has been received. It can then respond according to the value of the flag. 


The key to a delayed signal is that all functions return execution the exact point at which the 
program was interrupted. If the function returns normally the program continues execution just 
as if no signal occurred. 


Delaying a signal is especially useful in programs that must not be stopped at an arbitrary point. 
If, for example, a program updates a linked list, the action of a signal can be delayed to prevent 
the signal from interrupting the update and destroying the list. For example, in the following 
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program fragment the function delay used to catch the interrupt signal sets the globally-defined 
flag “‘sigflag” and returns immediately to the point of interruption. 


#include <signal.h> 
int sigflag=0; 


main () 

{ 
int delay (); 
int (*savesig)(); 
extern int sigflag; 


signal(SIGINT, delay); /* Delay the signal. */ 
updatelist(); 
savesig = signal(SIGINT, SIG_IGN); /* Disable the signal. */ 
if (sigflag) 
/* Process delayed signals if any. */ 


} 
delay () 
{ 
extern int sigflag; 


signal(SIGINT, delay); 
sigflag=1; 


In this example, if the signal is received while updatelist is executing, it is delayed until after 
updatelist returns. Note that the interrupt signal is disabled before processing the delayed signal 
to prevent a change to “sigflag”’ when it is being tested. 


Note that the system automatically resets a signal to its default action immediately after the 
signal is processed. If your program delays a signal, make sure that the signal is redefined after 
each interrupt. Otherwise, the default action will be taken on the next occurrence of the signal. 


7.3.2 Using Caught Signals With System Functions 


When a caught signal interrupts the execution of a slow XENIX system function, such as read or 
wait, the system forces the function to stop and return an error code. This action, unlike actions 
taken during execution of other functions, causes all processing performed by the system function 
to be discarded. A serious error can occur if a program interprets a system function error caused 
by caught signals as a normal error. For example, if a program receives a signal when reading the 
terminal, all characters read before the interruption are lost, making it appear as though no 
characters were typed. 


Whenever a program intends to use caught signals during calls to system functions, the program 
should include a check of the function return values to ensure that an error was not caused by an 
interruption. In the following program fragment, the program checks the current value of the 
interrupt flag “‘intflag” to make sure that the value EOF returned by getchar actually indicates 
the end of the file. 


if (getchar() == EOF) 
if (intflag) 
/* EOF caused by interrupt */ 
else 
/* true end-of-file */ 
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7.3.3 Using Signals in Interactive Programs 


Signals can be used in interactive programs to control the execution of the program’s various 
commands and operations. For example, a signal may be used in a text editor to interrupt the 
current operation (e.g., displaying a file) and return the program to a previous operation (e.g., 
waiting fora command). 


To provide this control, the function that redefines the signal’s action must be able to return 
execution of the program to a meaningful location, not just the point of interruption. The 
standard C library provides two functions to do this: setjmp and longjmp. The setjmp function 
saves a copy of a program’s execution state. The Jongjmp function changes the current execution 
state to a previously saved state. The functions cause a program to continue execution at an old 
location with old register values and status as if no operations had been performed between the 
time the state was saved and the time it was restored. 


The setjmp function has the form 
setyjmp (buffer) 


where buffer is the variable to receive the execution state. It must be explicitly declared with type 
jmpbuf before it is used in the call. For example, in the following program fragment setbuf copies 
the execution of the program to the variable “‘oldstate” defined with type jmpbuf. 


jmpbuf oldstate; 


setbuf(oldstate); 


Note that after a setbuf call, the buffer variable contains values for the program counter, the data 
and address registers, and the process status. These values must not be modified in any way. 


The Jongjmp function has the form 
longjmp (buffer) 


where buffer is the variable containing the execution state. It must contain values previously 
saved with a setbuf function. The function copies the values in the buffer variable to the program 
counter, data and address registers, and the process status table. Execution continues as if it had 
just returned from the setbuf function which saved the previous execution state. For example, in 
the following program fragment setbuf saves the execution state of the program at the location 
just before the main processing loop and /ongjmp restores it on an interrupt signal. 


#include <signal.h> 
#include <setjmp.h> 
jmpbuf sjbuf; 

main() 


int onintr(); 


setjmp(sjbuf); 
signal(SIGINT, onintr); 


/* main processing loop */ 


} 


onintr () 


printf("\nInterrupt\n"); 
longjmp(sjbuf); 
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In this example, the action of the interrupt signal as defined by onintr is to print the message 
“Interrupt” and restore the old execution state. When an interrupt signal is received in the main 
processing loop, execution passes to onintr which prints the message, then passes execution back 
to the main program function, making it appear as though control is returning from the setbuf 
function. 


7.4 Using Signals in Multiple Processes 


The XENIX system passes all signals generated at a given terminal to all programs invoked at 
that terminal. This means that a program can potentially be affected by a signal even if that 
program is executing in the background or as a child to some other program. The following 
sections explain how signals may be used in multiple processes. 


7.4.1 Protecting Background Processes 


Any program that has been invoked using the shell’s background symbol (&) is executed as a 
background process. Such programs usually do not use the terminal for input or output, and 
complete their tasks silently. Since these programs do not need additional input, the shell 
automatically disables the SIGINT and SIGQUIT signals before executing the program. This 
means INTs and QUITs generated from the terminal do not affect execution of the program. 
This is how the shell protects the program from signals intended for other programs invoked from 
the same terminal. 


In some cases, a program that has been invoked as a background process may also attempt to 
catch its own signals. If it succeeds, the protection from interruption given to it by the shell is 
defeated, and signals intended for other programs will interrupt the program. To prevent this, 
any program which is intended to be executed as a background process, should test the current 
state of a signal before redefining its action. A program should redefine a signal only if the signal 
has not been disabled. For example, in the following program fragment the action of the 
interrupt signal is changed only if the signal is not currently being ignored. 


#include <signal.h> 
main() 
int catch(); 


if (signal(SIGINT, SIG_ IGN) != SIG_IGN) 
signal(SIGINT, catch); 


/* Program body. */ 


This step lets a program continue to ignore signals if it is already doing so, and change the signal if 
it is not. 
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7.4.2 Protecting Parent Processes 


A program can create and wait for a child process that catches its own signals if and only if the 
program protects itself by disabling all signals before calling the wait function. By disabling the 
signals, the parent process prevents signals intended for the child processes from terminating its 
call to wait. This prevents serious errors that may result if the parent process continues execution 
before the child processes are finished. 


For example, in the following program fragment the interrupt signal is disabled in the parent 
process immediately after the child is created. 


#include <signal.h> 
main () 
int (*saveintr)(); 


if (fork () == 0) 
execi(.... )5 


saveintr = signal (SIGINT, SIG_IGN); 
wait( &status ); 
signal (SIGINT, saveintr); 


} 


The signal’s action is restored after the wait function returns normal control to the parent. 
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8.1 Introduction 


This chapter describes the standard C library functions that let programs share the resources of 
the XENIX system. The functions give a program the means to queue for the use and control of a 
given resource and to synchronize its use with use by other programs. 


In particular, this chapter explains how to 
— Allocate memory for dynamically required storage 
— _ Locka file to ensure exclusive use by a program 
— Usesemaphores to control access to a resource 


— Share data space to allow interaction between programs 
8.2 Allocating Space 


Some programs require significant changes to the size of their allocated memory space during 
different phases of their execution. The memory allocation functions of the standard C library let 
programs allocate space dynamically. This means a program can request a given number of 
bytes of storage for its exclusive use at the moment it needs the space, then free this space after it 
has finished using it. 


There are four memory allocation functions: malloc, calloc, realloc, and free. The malloc and 
calloc functions are used to allocate space for the first time. The functions allocate a given 
number of bytes and return a pointer to the new space. The realloc function reallocates an 
existing space, allowing it to be used in a different way. The free function allows allocated space 
to be re-used by one of the allocation functions. 


8.2.1 Allocating Space for a Variable 


The malloc function allocates space for a variable containing a given number of bytes. The 
function call has the form: 


malloc (size) 


where size is an unsigned number which gives the number of bytes to be allocated. For example, 
the function call 


table = malloc (4) 


allocates four bytes or storage. The function normally returns a pointer to the starting address of 
the allocated space, but will return the null pointer value if there is not enough space to allocate. 


The function is typically used to allocate storage for a group of strings that vary in length. For 
example, in the following program fragment malloc is used to allocate space for ten different 
strings, each of different length. 
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int 1; 
char temp[100], *strings[10]; 
unsigned isize; 


for ( i=0; i<10; i++) { 
scanf("%s", temp); 
isize = strlen(temp); 
string[i] = malloc(isize)+1; 
strepy(string[i],temp); 


} 


In this example, the strings are read from the standard input. Note that the strlen function is 
used to get the size in bytes of each string. 


8.2.2 Allocating Space for an Array 


The calloc function allocates storage for a given array and initializes each element in the new 
array to zero. The function call has the form: 


calloc (n, size) 


where n is the number of elements in the array, and size is the number of bytes in each element. 
The function normally returns a pointer to the starting address of the allocated space, but will 
return a null pointer value if there is not enough memory. For example, the function call 


table = calloc (10,4) 
allocates sufficient space for a 10 element array. Each element has 4 bytes. 


The function is typically used in programs which must process large arrays without knowing the 
size of an array in advance. For example, in the following program fragment calloc is used to 
allocate storage for an array of values read from the standard input. 

int 1; 

int *table; 

unsigned inum; 


scanf("%d", &inum); 

table = calloc (inum, sizeof(int)); 

for (i=0; i<inum; i++) 
scanf("%d", &table[i]); 


Note that the number of elements is read from the standard input before the elements are read. 


8.2.3 Reallocating Space 


The realloc function reallocates the space at a given address without changing the contents of the 
memory space. The function call has the form: 


realloc (ptr, size) 


where pir is a pointer to the starting address of the space to be reallocated, and size is an unsigned 
number giving the new size in bytes of the reallocated space. The function normally returns a 
pointer to the starting address of the allocated space, but will return a null pointer value if there is 
not enough space to allocate. 


This function is typically used to keep storage as compact as possible. For example, in the 
following program fragment realloc is used to remove table entries. 
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int *table, 1; 
unsigned inum; 


for (i=inum; i>-1; --i) { 
printf("%d\n, table[i]); 
table = realloc(table, i*sizeof(int)); 


} 


In this example, an entry is removed after it has been printed at the standard output, by reducing 
the size of the allocated space from its current length to the length given by “i*sizeof(int)”’. 


8.2.4 Freeing Unused Space 


The free function frees unused memory space that had been previously allocated by a malloc, 
calloc, or realloc function call. The function call has the form: 


free (ptr) 


where ptr is the pointer to the starting address of the space to be freed. This pointer must be the 
return value of a malloc, calloc, or realloc function. 


The function is used exclusively to free space which is no longer used or to free space to be used for 
other purposes. For example, in the following program fragment free frees the allocated space 
pointed to by “strings” if the first element is equal to zero. 


{ 


int *table; 


if ( table[(O0] == —1 ) 
free (table); 


8.3 Locking Files 


Locking a file is a way to synchronize file use when several processes may require access to a 
single file. The standard C library provides one file locking function, the locking function. This 
function locks any given section of a file, preventing all other processes which wish to use the 
section from gaining access. A process may lock the entire file or only a small portion. In any 
case, only the locked section is protected; all other sections may be accessed by other processes as 
usual. 


File locking protects a file from the damage that may be caused if several processes try to read or 
write to the file at the same time. It also provides unhindered access to any portion of a file for a 
controlling process. Before a file can be locked, however, it must be prepared using the open and 
Iseek functions described in Chapter 2, “Using the Standard I/O Functions.” To use the locking 
function, you must add the line 


#include <sys/locking.h> 


to the beginning of the program. The file sys/locking.h contains definitions for the modes used 
with the function. 


8.3.1 Preparing a File for Locking 


Before a file can be locked, it must first be opened using the open function, then properly 
positioned by using the /seek function to move the file’s character pointer to the first byte to be 
locked. 
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The open function is used once at the beginning of the program to open the file. The /seek 
function may be used any number of times to move the character pointer to each new section to be 
locked. For example, the following statements prepare the bytes at file position 1024 from the 
beginning of the reservations file for locking. 


fd = open("reservations", O RDONLY); 
lseek(fd, 1024, 0); 


8.3.2 Locking a File 


The locking function locks one or more bytes of a given file. The function call has the form: 
locking (filedes, mode, size) 


where filedes is the file descriptor of the file to be locked, mode is an integer value which defines 
the type of lock to be applied to the file , size is a long integer value giving the size in bytes of the 
portion of the file section to be locked or unlocked. The mode may be ““LK_LOCK” for locking 
the given bytes, or “LK_UNLCK” for unlocking them. For example, in the following program 
fragment /ocking locks 100 bytes at the current character pointer position in the file given by 
we Xs hase 


#include <sys/locking.h> 
int fd; 


fd = open("data", O RDWR); 
locking(fd, LK LOCK, 100L); 


The function normally returns the number of bytes locked, but will return —1 if it encounters an 
error. 


8.3.3 Program Example 


This section shows how to lock and unlock a small section in a file using the /ocking function. In 
the following program, the function locks 100 bytes in the file data which is opened for reading 
and writing. The locked portion of the file is accessed, then Jocking is used again to unlock the 
file. 
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#include <sys/locking.h> 


main() 
int fd, err; 
char *data; 
fd = open("data",O RDWR); /* Open data for R/W */ 
if (fd == —1 ) 
perror(""); 
else { 
lseek(fd, 100L, 0); /* Seek to pos 100 */ 
err = locking(fd, LK LOCK, 100L); /* Lock bytes 100-200 */ 
if (err == -1) { 
/* process error return */ 
/* read or write bytes 100 - 200 in the file */ 
lseek(fd, 100L, 0); /* Seek to pos 100 */ 
locking(fd, LK UNLCK, 100L); /* Unlock bytes 100-200 */ 
} 
} 


8.4 Using Semaphores 


The standard C library provides a group of functions, called the semaphore functions, which may 
be used to control the access to a given system resource. These functions create, open, and 
request control of “semaphores.” Semaphores are regular files that have names and entries in the 
file system, but contain no data. Unlike other files, semaphores cannot be accessed by more than 
one process at a time. A process that wishes to take control of a semaphore away from another 
process must wait until that process relinquishes control. Semaphores can be used to control a 
system resource, such as a data file, by requiring that a process gain control of the semaphore 
before attempting to access the resource. 


There are five semaphore functions: creatsem, opensem, waitsem, nbwaitsem, and sigsem. The 
creatsem function creates a semaphore. The semaphore may then be opened and used by other 
processes. A process can open a semaphore with the opensem function and request control of a 
semaphore with the waitsem or nbwaitsem function. Once a process has control of a semaphore it 
can carry out tasks using the given resource. All other processes must wait. When a process has 
finished accessing the resource, it can relinquish control of the semaphore with the sigsem 
function. This lets other processes get control of the semaphore and use the corresponding 
resource. 


8.4.1 Creating a Semaphore 


The creatsem function creates a semaphore, returning a semaphore number which may be used 
in subsequent semaphore functions. The function call has the form: 


creatsem (sem_name, mode) 


where sem_name is a character pointer to the name of the semaphore, and mode is an integer 
value which defines the access mode of the semaphore. Semaphore names have the same syntax 
as regular file names. The names must be unique. The function normally returns an integer 
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semaphore number which may be used in subsequent semaphore functions to refer to the 
semaphore. The function returns —1 if it encounters an error, such as creating a semaphore that 
already exists, or using the name of an existing regular file. 


The function is typically used at the beginning of one process to clearly define the semaphores it 
intends to share with other processes. For example, in the following program fragment creatsem 
creates a semaphore named “tty!” before preceding with its tasks. 


main () 


int ttyl; 
FILE ftty1; 


ttyl = creatsem("ttyl", 0777); 
fttyl = fopen("/dev/tty01", "w"); 
/* Program body. */ 
} 


Note that fopen is used immediately after creatsem to open the file /dev/tty0/ for writing. This is 
one way to make the association between a semaphore and a device clear. 


The mode ‘‘0777” defines the semaphore’s access permissions. The permissions are similar to the 
permissions of a regular file. A semaphore may have read permission for the owner, for users in 
the same group as the owner, and for all other users. The write and execution permissions have no 
meaning. Thus, “0777” means read permission for all users. 


No more than one process ever need create a given semaphore; all other processes simply open the 
semaphore with the opensem function. Once created or opened, a semaphore may be accessed 
only by using the waitsem, nbwaitsem, or sigsem functions. The creatsem function may be used 
more than once during execution of a process. In particular, it can be used to reset a semaphore if 
a process fails to relinquish control before terminating. Before resetting a semaphore, you must 
remove the associated semaphore file using the unlink function. 


8.4.2 Opening a Semaphore 


The opensem function opens an existing semaphore for use by the given process. The function 
call has the form: 


opensem (sem_name) 


where sem_name is a pointer to the name of the semaphore. This must be the same name used 
when creating the semaphore. The function returns a semaphore number that may be used in 
subsequent semaphore functions to refer to the semaphore. The function returns —1 if it 
encounters an error, such as trying to open a semaphore that does not exist or using the name of 
an existing regular file. 


The function is typically used by a process just before it requests control of a given semaphore. A 
process need not use the function if it also created the semaphore. For example, in the following 
program fragment opensem is used to open the semaphore named semaphore]. 


int sem1; 


if ( (seml = opensem("semaphorel")) != —1) 
waitsem(sem1); 


In this example, the semaphore number is assigned to the variable “sem1”’. If the number is not 
—1, then “sem1”’ is used in the semaphore function waitsem which requests control of the 
semaphore. 
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A semaphore must not be opened more than once during execution of a process. Although the 
opensem function does not return an error value, opening a semaphore more than once can lead to 
a system deadlock. 


8.4.3 Requesting Control of a Semaphore 


The waitsem function requests control of a given semaphore for the calling process. If the 
semaphore is available, control is given immediately. Otherwise, the process waits. The function 
call has the form: 


waitsem (sem num) 


where sem_num is the semaphore number of the semaphore to be controlled. If the semaphore is 
not available (if it is under control of another process), the function forces the requesting process 
to wait. If other processes are already waiting for control, the request is placed next in a queue of 
requests. When the semaphore becomes available, the first process to request control receives it. 
When this process relinquishes control, the next process receives control, and so on. The function 
returns —1 if it encounters an error such as requesting a semaphore that does not exist or 
requesting a semaphore that is locked to a dead process. 


The function is used whenever a given process wishes to access the device or system resource 
associated with the semaphore. For example, in the following program fragment waitsem signals 
the intention to write to the file given by “‘tty1”’. 

int ttyl; 

FILE ftty1; 


waitsem( ttyl ); 
fprintf( fttyl, "Changing tty driver\n"); 


The function waits until current controlling process relinquishes control of the semaphore before 
returning to the next statement. 


8.4.4 Checking the Status of a Semaphore 


The nbwaitsem function checks the current status of a semaphore. If the semaphore is not 
available, the function returns an error value. Otherwise, it gives immediate control of the 
semaphore to the calling process. The function call has the form: 


nbwaitsem (sem_num) 


where sem_num is the semaphore number of the semaphore to be checked. The function returns 
—1 if it encounters an error such as requesting a semaphore that does not exist. The function also 
returns —1 if the process controlling the requested semaphore terminates without relinquishing 
control of the semaphore. 


The function is typically used in place of waitsem to take control of a semaphore. 
8.4.5 Relinquishing Control of a Semaphore 


The sigsem function causes a process to relinquish control of a given semaphore and to signal this 
fact to all processes waiting for the semaphore. The function call has the form: 


sigsem (sem _num) 


where sem_num is the semaphore number of the semaphore to relinquish. The semaphore must 
have been previously created or opened by the process. Furthermore, the process must have been 
previously taken control of the semaphore with the waitsem or nbwaitsem function. The function 
returns —1 if it encounters an error such as trying to take control of a semaphore that does not 
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exist. 


The function is typically used after a process has finished accessing the corresponding device or 
system resource. This allows waiting processes to take control. For example, in the following 
program fragment sigsem signals the end of control of the semaphore “tty1”’. 


int ttyl; 
FILE temp, ftty1; 


waitsem( ttyl ); 

while ((c=fgetc(temp)) != EOF) 
fputc(c, fttyl); 

sigsem( ttyl ); 


This example also signals the end of the copy operation to the semaphore’s corresponding device, 
given by “fttyl”’. 


Note that a semaphore can become locked to a dead process if the process fails to signal the end of 
the control before terminating. In sucha case, the semaphore must be reset by using the creatsem 
function. 


8.4.6 Program Example 


This section shows how to use the semaphore functions to control the access of a system resource. 
The following program creates five different processes which vie for control of asemaphore. Each 
process requests control of the semaphore five times, holding control for one second, then 
releasing it. Although, the program performs no meaningful work, it clearly illustrates the use of 
semaphores. 
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#define NPROC 5 
char  semf[] = " kesemfXXXXXX'"; 
int sem num; 
int holdsem = 5; 
main() 
register 1, chid; 
mktemp(semf); 
if ((sem_num = creatsem(semf, 0777)) < 0) 
err("creatsem"); 
for (i = 1;i < NPROC; ++i) { 
if((chid = fork()) < 0) 
err("No fork"); 
else if(chid == 0) { 
if((sem_num = opensem(semf)) < 0) 
err("opensem"); 
doit(1); 
exit(0); 
} 
doit(0); 
for (i = 1; 1 < NPROC; ++i) 
while(wait((int *)0) < 0) 
unlink(semf); 
} 
doit (id) 
{ 
while(holdsem——) { 
if(waitsem(sem_ num) < 0) 
err("waitsem"); 
printf("%d\n", id); 
sleep(1); 
if(sigsem(sem_ num) < 0) 
err("sigsem"); 
} 
} 
err(s) 
char *s; 
{ 
perror(s); 
exit(1); 


The program contains a number of global variables. The array “semf” contains the semaphore 
name. The name is used by the creatsem and opensem functions. The variable “‘sem_num’”’ is the 
semaphore number. This is the value returned by creatsem and opensem and eventually used in 
waitsem and sigsem. Finally, the variable “holdsem” contains the number of times each process 
requests control of the semaphore. 


The main program function uses the mktemp function to create a unique name for the semaphore 
and then uses the name with creatsem to create the semaphore. Once the semaphore is created, it 
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begins to create child processes. These processes will eventually vie for control of the semaphore. 
As each child process is created, it opens the semaphore and calls the doit function. When control 
returns from doit the child process terminates. The parent process also calls the doit function, 
then waits for termination of each child process and finally deletes the semaphore with the unlink 
function. 


The doit function calls the waitsem function to request control of the semaphore. The function 
waits until the semaphore is available, it then prints the child number to the standard output, 
waits one second, and relinquishes control using the sigsem function. 


Each step of the program is checked for possible errors. If an error is encountered, the program 
calls the err function. This function prints an error message and terminates the program. 


8.5 Using Shared Data 


Shared memory is a method by which one process shares its allocated data space with another. 
Shared memory allows processes to pool information in a central location and directly access that 
information without the burden of creating pipes or temporary files. 


The standard C library provides several functions to access and control shared memory. The 
sdget function creates and/or adds a shared memory segment to a given process’s data space. To 
access a segment, a process must signal its intention with the sdenter function. Once a segment 
has completed its access, it can signal that it is finished using the the segment with the sdleave 
function. The sdfree function is used to remove a segment from a process’s data space. The 
sdgetv and sdwaitv functions are used to synchronize processes when several are accessing the 
segment at the same time. 


To use the shared data functions, you must add the line 
#include <sd.h> 


at the beginning of the program. The sd.h file contains definitions for the manifest constants and 
other macros used by the functions. 


8.5.1 Creating a Shared Data Segment 


The sdget function creates a shared data segment for the current process and attaches the 
segment to the process’s data space. The function call has the form: 


sdget (path, flag , size, mode ) 


where path is a character pointer to a valid pathname, flag is an integer value which defines how 
the segment should be created, size is an integer value which defines the size in bytes of the 
segment to be created, and mode is an integer value which defines the access permissions to be 
given to the segment. The flag may be a combination of SD_CREAT for creating the segment, and 
SD RDONLY for attaching the segment for reading only or SD_WRITE for attaching the 
segment for reading and writing. You may also use SD UNLOCK for allowing simultaneous 
access by multiple processes. The values can be combined by logically ORing them. The function 
returns the address of the segment if it has been successfully created. Otherwise, the function 
returns —1. 


The function is typically used by just one process to create a segment that it will share with 
several other processes. For example, in the following fragment, the program uses sdget to create 
a segment and attach it for reading and writing. The address of the new segment is assigned to 
shared. 
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#include <sd.h> 
main () 
char *shared; 


shared = sdget( "/tmp/share", SD CREATSD WRITE, 512, 0777 ); 
} 


When the segment is created, the size “512” and the mode “0777” are used to define the 
segment’s size in bytes and access permissions. Access permissions are similar to permissions 
given to regular files. A segment may have read or write permission for the owner of the process, 
for users belonging to the same group as the owner, and for all other users. Execute permission 
for a segment has no meaning. For example, the mode “0777” means read and write permission 
for everyone, but “0660” means read and write permissions for the owner and group processes 
only. When first created, a segment is filled with zeroes. 


Note that the SD_UNLOCK flag used on systems without hardware support for shared data may 
severely degrade the execution performance of the system. 


8.5.2 Attaching a Shared Data Segment 


The sdget function can also be used to attach an existing shared data segment to a process’s data 
space. In this case, the function call has the form 


sdget( path, flags ) 


where path is a character pointer to the pathname of an shared data segment created by some 
other process, and flag is an integer value which defines how the segment should be attached. The 
flag may be SD_RDONLY for attaching the segment for reading only, or SD WRITE for 
attaching the segment for reading and writing. If the function is successful, it returns the address 
of the new segment. Otherwise, it returns —1. 


The function can be used to attach any shared data segment a process may wish to access. For 
example, in the following fragment, the program uses sdget to attach the segments associated 
with the files /tmp/sharel and /tmp/share2 for reading and writing. The addresses of the new 
segments are assigned to the pointer variables sharel and share2. 


#include <sd.h> 
main () 
char *sharel, *share?; 


sharel = sdget( "/tmp/sharel", SD WRITE ); 
share2 = sdget( "/tmp/share2", SD WRITE ); 


} 


Sdget returns an error value to any process that attempts to access a shared data segment without 
the necessary permissions. The segment permissions are defined when the segment is created. 


8.5.3 Entering a Shared Data Segment 


The sdenter signals a process’s intention to access the contents of a shared data segment. A 
process cannot access the contents of the segment unless it enters the segment. The function call 
has the form: 
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sdenter (addr, flag) 


where addr is a character pointer to the segment to be accessed, and flag is an integer value which 
defines how the segment is to be accessed. The flag may be SD RDONLY for indicating read only 
access to the segment, SD _ WRITE for indicating write access to the segment, or SD_ NOWAIT for 
returning an error if the segment is locked and another process is currently accessing it. These 
values may also be combined by logically ORing them. The function normally waits for the 
segment to become available before allowing access to it. A segment is not available if the 
segment has been created without SD_UNLOCK flag and another process is currently accessing 
it. 


Once a process has entered a segment it can examine and modify the contents of the segment. For 
example, in the following fragment, the program uses sdenter to enter the segment for reading 
and writing, then sets the first value in the segment to 0 if it is equal to 255. 


#include <sd.h> 


main () 
char *share; 
share = sdget( "/tmp/share", SD_WRITE ); 
sdenter(share, SD WRITE); 
if ( share[O] == 255 ) 
share[0] = 0; 
} 


In general, it is unwise to stay in a shared data segment any longer than it takes to examine or 
modify the desired location. The sdleave function should be used after each access. When in a 
shared data segment, a program should avoid using system functions. System functions can 
disrupt the normal operations required to support shared data and may cause some data to be 
lost. In particular, if a program creates a shared data segment that cannot be shared 
simultaneously, the program must not call the fork function when it is also accessing that 
segment. 


8.5.4 Leaving a Shared Data Segment 


The sdleave function signals a process’s intention to leave a shared data segment after reading or 
modifying its contents. The function call has the form: 


sdleave (addr) 


where addr is a pointer with type char to the desired segment. The function returns —1 if it 
encounters an error, otherwise it returns 0. The return value is always an integer. 


The function should be used after each access of the shared data to terminate the access. If the 
segment’s lock flag is set, the function must be used after each access to allow other processes to 
access the segment. For example, in the following program fragment sdleave terminates each 
access to the segment given by “shared”’. 
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#include <sd.h> 


main () 
int 1 = 0; 
char c, *share; 
share = sdget("/tmp/share", SD RDONLY); 
sdenter(share, SD RDONLY),; 
c = *share; 
sdleave(share); 
while (c!=0) { 
putchar(c); 
i++; 
sdenter(share, SD RDONLY),; 
c = share[i]; 
sdleave(share); 
} 


8.5.5 Getting the Current Version Number 


The sdgetv function returns the current version number of the given data segment. The function 
call has the form: 


sdgetv (addr) 


where addr is a character pointer to the desired segment. A segment’s version number is initially 
zero, but it is incremented by one whenever a process leaves the segment using the sdleave 
function. Thus, the version number is a record of the number of times the segment has been 
accessed. The function’s return value is always an integer. It returns —1 if it encounters an error. 


The function is typically used to choose an action based on the current version number of the 
segment. For example, in the following program fragment sdgetv determines whether or not 
sdenter should be used to enter the segment given by “‘shared”’. 


#include <sd.h> 

char *shared; 

if (sdgetv(shared) > 10) 
sdenter(shared); 


In this example, the segment is entered if the current version number of the segment is greater 
than “10”. 


8.5.6 Waiting for a Version Number 


The sdwaitv function causes a process to wait until the version number for the given segment is no 
longer equal to a given version number. The function call has the form: 


sdwaitv (addr, vnum) 


where addr is a character pointer to the desired segment, and vnum is an integer value which 
defines the version number to wait on. The function normally returns the new version number. It 
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returns —1 if it encounters anerror. The return value is always an integer. 


The function is typically used to synchronize the actions of two separate processes. For example, 
in the following program fragment the program waits while the program corresponding to the 
version number “‘vnum”’ performs its operations in the segment. 


#include <sd.h> 
main () 


char *share; 
int change; 


vnum = sdgetv( share ); 


i=0; 

if ( sdwaitv( share, vnum ) == —1 ) 
fprintf(stderr, "Cannot find segment\n"); 

else 


sdenter( share ); 


If an error occurs while waiting, an error message is printed. 
8.5.7 Freeing a Shared Data Segment 


The sdfree function detaches the current process from the given shared data segment. The 
function call has the form: 


sdfree (addr) 


where adadr is a character pointer to the segment to be set free. The function returns the integer 
value 0, if the segment is freed. Otherwise, it returns —1. 


If the process is currently accessing the segment, sdfree automatically calls sdleave to leave the 
segment before freeing It. 


The contents of segments that have been freed by all attached processes are destroyed. To 
reaccess the segment, a process must recreate it using the sdget function and SD_CREAT flag. 


8.5.8 Program Example 


This section shows how to use the shared data functions to share a single data segment between 
two processes. The following program attaches a data segment named /tmp/share and then uses 
it to transfer information to between the child and parent processes. 
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# include <sd.h> 
main() 


char *share, message[12]; 
int 1, vnum; 


share = sdget("/tmp/share"\SSD CREATSD WRITE, 12, 0777); 


if (fork()==0) { 
for (i=0; i<4; i++) { 
sdenter(share, SD WRITE); 
strncpy(message, share, 12); 
strncpy(share,"Shared data", 12); 
vnum=sdgetv(share); 
sdleave(share); 
sdwaitv(share, vnum+1); 
printf("Child: %d - %s\n", i, message); 
} 
sdenter(share, SD WRITE); 
strncpy(message, share, 12); 
strncpy(share,"Shared data", 12); 
sdleave(share); 
printf("Child: %d - %s\n", i, message); 
exit(0); 
j 


for (i=0; i<5; i++) { 

sdenter(share, SD WRITE); 
strncpy(message, share, 12); 
strncpy(share,"Data shared", 12); 
vnum=sdgetv(share); 

sdleave(share); 

sdwaitv(share, vnum+1); 

printf("Parent: %d - %s\n", i, message); 


sdfree(share); 


In this program, the child process inherits the data segment created by the parent process. Each 
process accesses the segment 5 times. During the access, a process copies the current contents of 
the segment to the variable message and replaces the message with one of its own. It then displays 
message and continues the loop. 


To synchronize access to the segment, both the parent and child use the sdgetv and sdwaitv 
functions. While a process still has control of the segment, it uses sdgetv to assign the current 
version number to the variable vnum. It then uses this number ina call to sdwaitv to force itself to 
wait until the other process has accessed the segment. Note that the argument to sdwaitv is 
actually “vnum+1’’. Since vnum was assigned before the sdleave call, it is exactly one less than 
the version number after the sdleave call. It is assigned before the sdleave call to ensure that the 
other process does modify the current version number before the current process has a chance to 
assign it tovnum. 


The last time the child process accesses the segment, it displays the message and exits without 
calling the sdwaitv function. This is to prevent the process from waiting forever, since the parent 
has already exited and can no longer modify the current version number. 
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9.1 Introduction 


The XENIX system automatically detects and reports errors that occur when using standard C 
library functions. Errors range from problems with accessing files to allocating memory. In most 
cases, the system simply reports the error and lets the program decide how to respond. The 
XENIX system terminates a program only if a serious error has occurred, such as a violation of 
memory space. 


This chapter explains how to process errors, and describes the functions and variables a program 
may use respond to errors. 


9.2 Using the Standard Error File 


The standard error file is a special output file that can be used by a program to display error 
messages. The standard error file is one of three standard files (standard input, output, and error) 
automatically created for the program when it is invoked. 


The standard error file, like the standard output, is normally assigned to the user’s terminal 
screen. Thus, error messages written to the file are displayed at the screen. The file can also be 
redirected by using the shell’s redirection symbol (>) For example, the following command 
redirects the standard error file to the file erroriist. 


dial 2>errorlist 
In this case, subsequent error messages are written to the given file. 


The standard error file, like the standard input and standard output, has predefined file pointer 
and file descriptor values. The file pointer stderr may be used in stream functions to copy data to 
the error file. The file descriptor 2 may be used in low-level functions to copy data to the file. For 
example, in the following program fragment stderr is used to write the message “Unexpected end 
of file” to the standard error file. 


if ( (c=getchar()) == EOF) 
fprintf(stderr, "Unexpected end of file.\n"); 


The standard error file is not affected by the shell’s pipe symbol (|). This means that even if the 
standard output of a program is piped to another program, errors generated by the program will 
still appear at the terminal screen (or in the appropriate file if the standard error is redirected). 


9.3 Using the errno Variable 


The errno variable is a predefined external variable which contains the error number of the most 
recent XENIX system function error. Errors detected by system functions, such as access 
permission errors and lack of space, cause the system to set the errno variable to a number and 
return control to the program. The error number identifies the error condition. The variable may 
be used in subsequent statements to process the error. 


The errno variable is typically used immediately after a system function has returned an error. In 
the following program fragment, errno is used to determine the course of action after an 
unsuccessful call to the open function. 
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if ( (fd=open("accounts", O RDONLY)) == —1 ) 
switch (errno) { 
case(EACCES): 
fd = open("/usr/tmp/accounts",O RDONLY)); 
break; 
default: 
exit(errno); 
} 


In this example, if errno is equal to EACCES (a manifest constant), permission to open the file 
accounts in the current directory is denied, so the file is opened in the directory /usr/tmp instead. 
If the variable is any other value, the program terminates. 


To use the errno variable in a program, it must be explicitly defined as an external variable with 
int type. Note that the file errno.h contains manifest constant definitions for each error number. 
These constants may be used in any program in which the line 


#include <errno.h> 


is placed at the beginning of the program. The meaning of each manifest constant is described in 
Intro(S) inthe XENIX Reference Manual. 


9.4 Printing Error Messages 


The perror function copies a short error message describing the most recent system function error 
to the standard error file. The function call has the form: 


perror (s) 
where s is a pointer to a string containing additional information about the error. 


The perror function places the given string before the error message and separates the two with a 
colon (:). Each error message corresponds to the current value of the errno variable. For 
example, in the following program fragment perror displays the message 


accounts: Permission denied. 
if errno is equal to the constant EACCES. 


if ( errno == EACCES ) { 

perror("accounts"); 

fd = open ("/usr/tmp/accounts", O RDONLY)); 
} 


All error messages displayed by perror are stored in an array named sys errno, an external array 
of character strings. The perror function uses the variable errno as the index to the array element 
containing the desired message. 


9.5. Using Error Signals 


Some program errors cause the XENIX system to generate error signals. These signals are passed 
back to the program that caused the error and normally terminate the program. The most 
common error signals are SIGBUS, the bus error signal, SIGFPE, the floating point exception 
signal, SIGSEGV, the segment violation signal, SIGSYS, the system call error signal, and 
SIGPIPE, the pipe error signal. Other signals are described in signal(S) in the XENIX Reference 
Manual. 


A program can, if necessary, catch an error signal and perform its own error processing by using 
the signal function. This function, as described in Chapter 7, “Using Signals” can set the action 
of a signal toa user-defined action. For example, the function call 
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signal(SIGBUS, fixbus); 


sets the action of the bus error signal to the action defined by the user-supplied function fixbus. 
Such a function usually attempts to remedy the problem, or at least display detailed information 
about the problem before terminating the program. 


For details about how to catch, redefine, and restore these signals, see Chapter 7. 


9.6 Encountering System Errors 


Programs that encounter serious errors, such as hardware failures or internal errors, generally do 
not receive detailed reports on the cause of the errors. Instead, the XENIX system treats these 
errors as “system errors’’, and reports them by displaying a system error message on the system 
console. This section briefly describes some aspects of XENIX system errors and how they relate 
to user programs. For a complete list and description of XENIX system errors, see messages (M) 
in the XENIX Reference Manual. 


Most system errors occur during calls to system functions. If the system error is recoverable, the 
system will return an error value to the program and set the errno variable to an appropriate 
value. No other information about the error is available. 


Although the system lets two or more programs share a given resource, it does not keep close 
track of which program is using the resource at any given time. When an error occurs, the system 
returns an error value to all programs regardless of which caused the error. No information 
about which program caused the error is available. 


System errors that occur during routine I/O operations initiated by the XENIX system itself 
generally do not affect user programs. Such errors cause the system to display appropriate 
system error messages on the system console. 


Some system errors are not detected by the system until after the corresponding function has 
returned successfully. Such errors occur when data written to a file by a program has been 
queued for writing to disk at a more convenient time, or when a portion of data to be read from 
disk is found to already be in memory and the remaining portion is not read until later. In such 
cases, the system assumes that the subsequent read or write operation will be carried out 
successfully and passes control back to the program along with a successful return value. If 
operation is not carried out successfully, it causes a delayed error. 


When a delayed error occurs, the system usually attempts to return an error on the next call toa 
system function that accesses the same file or resource. If the program has already terminated or 
does not make a suitable call, then the error is not reported. 
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Assembly Language Interface 


A.1 Introduction 


When mixing MC68000 assembly language routines and compiled C routines, there are several 
things to be aware of: 


e Registers and Return Values 
e Calling Sequence 
e Stack Probes 


With an understanding of these three topics, you should be able to write both C programs that 
call MC68000 assembly language routines and assembly language routines that call compiled C 
routines. 


A.1.1 Registers and Return Values 


Function return values are passed in registers if possible. The set of machine registers used is 
called the save set, and includes the registers from d2-d7 and a2-a7 that are modified by a 
routine. The compiler assumes that these registers are preserved by the callee, and saves them 
itself when it is generating code for the callee (when a C compatible routine is called by another 
routine, we refer to the calling routine as the caller. We refer to the called routine as the callee.) 
Note that a6 and a7 are in effect saved by a link instruction at procedure entry. 


The function return value is in dO. The current floating point implementation returns the high 
order 32 bits of doubles in d/, and the low order 32 bits in dO. Functions that return structure 
values (not pointers to the values) do so by loading dO with a pointer to a static buffer containing 
the structure value. 


This makes the following two functions equivalent: 


struct foo proc (){ 
struct foo this; 


return (this); 


} 
struct foo *proc (){ 
struct foo this; 
static struct foo temp; 
temp = this; 
return (&temp); 


This implementation allows recursive reentrancy (as long as the explicit form is not used, since 
the first sequence is indivisible but not the second). However, this implementation does not per- 
mit multitasking reentrancy. Note that the latter includes the XENIX call. 


and can not be implemented as they are on the PDP-11, because each procedure saves only the re- 


gisters from the save set that it will modify. This makes it difficult to get back the current values 
of the register variables of the procedure that is being setjmped to. Hence, register variable values 
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after a longjmp are the same as before a corresponding setjmp is called. If you need local vari- 
ables to change between the call of setjmp and longjmp, they cannot be register variables. 


A.1.2 Calling Sequence 


The calling sequence is straightforward: arguments are pushed on the stack from the last to first: 
i.e., from right to left as you read them in the C source. The push quantum is 4 bytes, so if you are 
pushing a character, you must extend it appropriately before pushing. Structures and floating 
point numbers that are larger than 4 bytes are pushed in increments of 4 bytes so that they end up 
in the same order in stack memory as they are in any other memory. This means pushing the last 
word first and longword padding the last word (the first pushed) if necessary. The caller is respon- 
sible for removing his own arguments. Typically, an 


addql #constant,sp 


is done. It is not really important whether the caller actually pushes and pops his arguments or 
just stores them in a static area at the top of the stack, but the debugger, adb, examines the addql 
or addw from the sp to decide how many arguments there were. 


A.1.3 Stack Probes 


Note 


This information is provided as reference material ONLY. The XENIX kernal does not 
dynamically extend stack, as there is no hardware support to do so. 


XENIX is designed to dynamically allocate stack for local variables, function arguments, return 
addresses, etc. To do this, the XENIX kernel checks the offending instruction when a memory 
fault occurs. If it is a stack reference, the kernel maps enough stack memory for the instruction to 
complete its execution successfully. Then the procedure continues execution where it left off. 
Generally, this means restarting the offending memory reference instruction (usually a push or 
store). Unfortunately, the MC68000 does not provide a way to restart instructions. 


Therefore, we need to perform a special instruction, which we call a stack probe, that potentially 
causes the memory fault, but that has no effect other than the memory fault itself. The kernel can 
then allocate any needed stack memory, ignore the fact that the stack probe instruction did not 
complete, and continue on to the next instruction. When we perform a stack probe and a memory 
fault occurs, the kernel allocates additional memory for the stack. The stack probe instruction 
for 68000 XENIX is 


tstb -value(sp) 


Value must be negative: since a negative index from the stack pointer is above the top of the stack 
an otherwise absurd reference XENIX knows that this instruction can only be a stack probe. 


For the general case, use the following procedure entry sequence: 
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procedure entry: 
link a6,#-Savesize 
tstb -pushsize-slop-8 (sp) 


Any registers among d2-d7 and a2-aS that are used in this procedure are saved with a moveml in- 
struction after this sequence. The number of registers saved in the moveml needs to be accounted 
for in the push size. Thus, pushsize is the sum of the number of bytes pushed as temporaries, save 
areas, and arguments by the whole procedure. The 8 bytes are the space for the return address 
and frame pointer save (by the link instruction) of a nested call. The s/op is tolerance so that ex- 
tremely short runtimes that use little stack do not need to perform a stack probe. The tolerance is 
intentionally kept small to conserve memory, so make sure you understand what you are doing 
before you consider leaving out a stack probe in your assembly procedures. 


In most cases, unless you are pushing huge structures or doing tricks with the stack within your 
procedure, you can use the following instruction for your stack probe: 


tstb -100(sp) 
This makes sure that enough space has been allocated for most of the usual things you might do 
with the stack and is enough for the XENIX runtimes that do not perform stack probes. Note that 


you do not need to consider space allocated by the link instruction in this stack probe, since it is al- 
ready added by indexing off the stack pointer. 
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B.1 Introduction 


This appendix lists some of the differences between XENIX 2.3, XENIX 3.0, UNIX V7, and UNIX 
System 3.0. It is intended to aid users who wish to convert system calls in existing application 
programs for use on other systems. 


B.2 Executable File Format 


Both XENIX 3.0 and UNIX System 3.0 execute only those programs with the x.out executable 
file format. The format is similar to the old a.out format, but contains additional information 
about the executable file such as text and data relocation bases, target machine identification, 
word and byte ordering, symbol table and relocation tabie format. The x.out file also contains the 
revision number of the kernel which is used during execution to control access to system func- 
tions. To execute existing programs in a.out format, you must first convert to the x.out format. 
The format is described in detail in x.out(F) in the XENIX Reference Manual. 


B.3 Revised System Calls 


Some system calls in XENIX 3.0 and UNIX System 3.0 have been revised and do not perform the 
same tasks as the corresponding calls in previous systems. To provide compatibilty for old pro- 
grams, XENIX 3.0 and UNIX System 3.0 maintain both the new and the old system calls and au- 
tomatically check the revision information in the x.out header to determine which version of a 
system call should be made. The following table lists the revised system calls and their previous 
versions. 


System Call# XENIX2.3function System 3 function 


35 ftime unused 
38 unused clocal 
39 unused setpgrp 
40 unused cxenix 
ay unused utssys 
62 clocal fentl 
63 cxenix ulimit 


The cxenix function provides access to system calls unique to XENIX System 3.0. The clocal 
function provides access to all calls unique toan OEM. 


B.4 Version 7 Additions 

XENIX 3.0 maintains a number of UNIX V7 features that were dropped from UNIX System 3.0. 
In particular, XENIX 3.0 continues to support the dup2 and ftime functions. The ftime function, 
used with the ctime function, provides the default value for the time zone when the TZ environ- 
ment variable has not been set. 

B.5 Changes to the ioctl Function 

XENIX 3.0 and 1 System 3.0 have a full set of XENIX 2.3-compatible ioct/ calls. Furthermore, 


XENIX 3.0 has resolved problems that previously hindered UNIX System 3.0 compatibility. For 
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convenience, XENIX 2.3-compatible ioct/ calls can be executed by a UNIX System 3.0 execu- 
table. The available XENIX 2.3 ioct/ calls are: TIOCSETP, TIOCSETN, TIOCGETP, TIOCSETC, 
TIOCGETC, TIOCEXCL, TIOCNXCL, TIOCHPCL, TIOCFLUSH, TIOCGETD, and TIOCSETD. 


B.6 Pathname Resolution 


If a null pathname is given, XENIX 2.3 interprets the name to be the current directory, but UNIX 
System 3.0 considers the name to be an error. XENIX 3.0 uses the version number in the x.out 
header to determine what action to take. 


If the symbol “..” is given as a pathname when in a root directory that has been defined using the 
chroot function, XENIX 2.3 moves to the next higher directory. XKENIX 3.0 also allows the “‘..” 
symbol, but restricts its use to the super-user. 


B.7 Using the mount and chown Functions 


Both XENIX 3.0 and UNIX System 3.0 restrict the use of the mount system call to the super-user. 
Also, both allow the owner of a file to use chown function to change the file ownership. 


B.8 Super-Block Format 


Both UNIX System 3.0 and UNIX System 5.0 have new super-block formats. XENIX 3.0 uses 
the System 5.0 format, but uses a different magic number for each revision. The XENIX 3.0 
super-block has an additional field at the end which can be used to distinguish between XENIX 
2.3 and 3.0 super-blocks. XENIX 3.0 checks this magic number at boot time and during a mount. 
If a XENIX 2.3 super-block is read, XENIX 3.0 converts it to the new format internally. Simi- 
larly, if a XENIX 2.3 super-block is written, XENIX 3.0 converts it back to the old format. This 
permits XENIX 2.3 kernels to be run on file systems also usable by UNIX System 3.0. 


B.9 Separate Version Libraries 
XENIX 3.0 and UNIX System 3.0 support the construction of XENIX 2.3 executable files. These 


systems maintain both the new and old versions of system calls in separate libraries and include 
files. 
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abort 

abs 

access 

acct 

alarm 

assert 

atof, atoi, atol 

bessel, j0, j1, jn, yO, y1, yn 
bsearch 

chdir 

chmod 

chown 

chroot 

chsize 

close 

cony, toupper, tolower, toascii 
creat 

creatsem 

crypt, setkey, encrypt 
ctermid 

ctime, localtime, gmtime, 
asctime, tzset 

ctype, isalpha, isupper, 
islower, isdigit, isxdigit, 
isalnum, isspace, ispunct, 
isprint, isgraph, iscntrl, isascii 
curses 

cuserid 

dbm, dbminit, fetch, store, 
delete, firstkey, nextkey 
defopen, defread 

dup, dup2 

ecvt, fcvt, gcvt 

end, etext, edata 

execl, execv, execle, execve, 
execip, execyp 

exit 

exp, log, pow, sqrt, log10 


fclose, fflush 
fentl 
ferror, feof, clearerr, fileno 


Introduces. system services, library routines and error 
numbers. 

Converts between long integer and base 64 ASCII. 
Generates an IOT fault. 

Returns an integer absolute value. 
Determines accessibility of a file. 

Enables or disables process accounting. 

Sets a process’ alarm clock. 

Helps verify validity of program. 

Converts ASCII to numbers. 

Performs Bessel functions. 

Performs a binary search. 

Changes the working directory. 

Changes mode of a file. 

Changes the owner and group of a file. 
Changes the root directory. 

Changes the size of a file. 

Closes a file descriptor. 

Translates characters. 

Creates a new file or rewrites an existing one. 
Creates an instance of a binary semaphore. 
Performs encryption functions. 

Generates a filename for a terminal. 


Converts date and time to ASCII. 


Classifies characters. 
Performs screen and cursor functions. 
Gets the login name of the user. 


Performs database functions. 
Reads default entries. 

Duplicates an open file descriptor. 
Performs output conversions. 
Last locations in program. 


Executes a file. 

Terminates a process. : 
Performs exponential, logarithm, power, square root func- 
tions. 

Closes or flushes a stream. 

Controls open files. 

Determines stream status. 


floor, fabs, ceil, fmod 


fopen, freopen, fdopen 

fork 

fread, fwrite 

frexp, ldexp, modf 

fseek, ftell, rewind 

gamma 

getc, getchar, fgetc, getw 
getcwd 

geteny 

getgrent, getgrgid, getgrnam, 
setgrent, endgrent 

getlogin 

getopt 

getpass 

getpid, getpgrp, getppid 

getpw 

getpwent, getpwuid, 
getpwnam, setpwent, endpwent 
gets, fgets 
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hypot, cabs 

ioctl 

kill 

13tol, Itol3 

link 

lock 

lockf 

locking 

Isearch 

Iseek 

malloc, free, realloc, calloc 
mknod 

mktemp 

monitor 

mount 

nap 

nice 
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open 

opensem 

pause 

perror, sys _errlist,sys_nerr, 
errno 

pipe 

plock 

popen, pclose 

printf, fprintf, sprintf 
profil 

ptrace 


Performs absolute value, floor, ceiling and remainder func- 
tions. 

Opens a stream. 

Creates a new process. 

Performs buffered binary input and output. 

Splits floating-point number into a mantissa and an exponent. 
Repositions a stream. 

Performs log gamma function. 

Gets character or word froma stream. 

Gets pathname of current working directory. 

Gets value for environment name. 


Get group file entry. 

Gets login name. 

Gets option letter from argument vector. 

Reads a password. 

Gets process, process group, and parent process IDs. 
Gets password for a given user ID. 


Gets password file entry. 

Gets a string from a stream. 

Gets real user, effective user, real group, and effective group 
IDs. 

Determines Euclidean distance. 

Controls character devices. 

Sends a signal to a process or a group of processes. 
Converts between 3-byte integers and long integers. 
Links a new filename to an existing file. 

Locks a process in primary memory. 

Provide semaphores and record locking in files. 
Locks or unlocks a file region for reading or writing. 
Performs linear search and update. 

Moves read/write file pointer. 

Allocates main memory. 

Makes a directory, or a special or ordinary file. 
Makes a unique filename. 

Prepares execution profile. 

Mounts a file system. 

Suspends execution for a short interval. 

Changes priority of a process. 

Gets entries from name list. 

Opens file for reading or writing. 

Opens a semaphore. 

Suspends a process until a signal occurs. 


Sends system error messages. 

Creates an interprocess pipe. 

Lock process, text, or data in memory. 
Initiates I/O to or from a process. 
Formats output. 

Creates an execution time profile. 
Traces a process. 


putc, putchar, fputc, putw 
putpwent 

puts, fputs 

qsort 

rand, srand 

rdchk 

read 

regex, regcmp 

regexp 

sbrk, brk 

scanf, fscanf, sscanf 
sdenter, sdleave 

sdget 

sdgety, sdwaitv 

setbuf 

setjmp, longjmp 

setpgrp 

setuid, setgid 

shutdn 

signal 

sigsem 

sinh, cosh, tanh 

sleep 

ssignal, gsignal 

stat, fstat 

stdio 

stime 

string, strcat, strncat, strcmp, 
strncmp, strcpy, strncpy, 
strlen, strchr, strrchr, strpbrk, 
strspn, strcspn, strtok, strdup 
swab 

sync 

system 

termcap, tgetent, tgetnum, 
tgetflag, tgetstr, tgoto, tputs 
time, ftime 

times 

tmpfile 

tmpnam 

trig, sin, cos, tan, asin, acos, 
atan, atan2 

ttyname, isatty 

ulimit 

umask 

umount 

uname 

ungetc 

unlink 

ustat 

utime 


Puts a character or word ona stream. 

Writes a password file entry. 

Puts a string on a stream. 

Performs a sort. 

Generates a random number. 

Checks to see if there is data to be read. 

Reads from a file. 

Compiles and executes regular expressions. 
Regular expression compile and match routines. 
Changes data segment space allocation. 
Converts and formats input. 

Synchronizes access to a shared data segment. 
Attachs and detachs a shared data segment. 
Synchronizes shared data access. 

Assigns buffering toa stream. 

Performs a nonlocal “goto”’. 

Sets process group ID. 

Sets user and group IDs. 

Flushes block I/O and halts the CPU. 
Specifies what to do upon receipt of a signal. 
Signals a process waiting on a semaphore. 
Performs hyperbolic functions. 

Suspends execution for an interval. 
Implements software signals. 

Gets file status. 

Performs standard buffered input and output. 
Sets the time. 


Perform string operations. 
Swaps bytes. 

Updates the super-block. 
Executes a shell command. 


Performs terminal functions. 

Gets time and date. 

Gets process and child process times. 
Creates a temporary file. 

Creates a name for a temporary file. 


Performs trigonometric functions. 

Finds the name of a terminal. 

Gets and sets user limits. 

Sets and gets file creation mask. 
Unmounts a file system. 

Gets name of current XENIX system. 
Pushes character back into input stream. 
Removes directory entry. 

Gets file system statistics. 

Sets file access and modification times. 


wait Waits for a child process to stop or terminate. 

waitsem, nbwaitsem Awaits and checks access to a resource governed by a sema- 
phore. 

write Writes toa file. 
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Name 


intro — Introduces system services, library routines and error numbers. 


Syntax 


#include <errno.h> 


Description 


This section describes all system services. System services include all routines or system calls that are 
available in the operating system kernel. These routines are available to a C program automatically as 
part of the standard library libc. Other routines are available in a variety of libraries. On 8086/88 and 
286 systems, versions for Small, Middle, and Large model programs are provided (that is, three of each 
library). 


To use routines in a program that are not part of the standard library libc, the appropriate library must 
be linked. This is done by specifying —lname to the compiler or linker, where name is the name listed 
below. For example —lm, and —ltermcap are specifications to the linker to search the named libraries 
for routines to be linked to the object module. The names of the available libraries are: 


Cc The standard library containing all system call interfaces, Standard I/O routines, and other 
general purpose services. 


m The standard math library. 

termcap Routines for accessing the termcap data base describing terminal characteristics. 
curses Screen and cursor manipulation routines. 

dbm Data base management routines. 

X The standard xenix library. 


Most services that are part of the operating system kernel have one or more error returns. An error con- 
dition is indicated by an otherwise impossible returned value. This is almost always —1; the individual 
descriptions specify the details. An error number is also made available in the external variable errno. 
Errno is not cleared on successful calls, so it should be tested only after an error has been indicated. 


All of the possible error numbers are not listed in each system call description because many errors are 
possible for most of the calls. The following is a complete list of the error numbers and their names as 
defined in <errno.h>. 


1 EPERM Not owner 
Typically this error indicates an attempt to modify a file in some way forbidden except to its owner 
Or super-user. It is also returned for attempts by ordinary users to do things allowed only to the 
super-user. 


2 ENOENT No such file or directory 
This error occurs when a filename is specified and the file should exist but doesn’t, or when one of 
the directories in a pathname does not exist. 


3 ESRCH No such process 
No process can be found corresponding to that specified by pid in kill or ptrace. 
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4 


10 


if 


LZ 


L3 


14 


ie 


16 


17 


18 


EINTR Interrupted system call 
An asynchronous signal (such as interrupt or quit), which the user has elected to catch, occurred du- 
ring a system call. If execution is resumed after processing the signal, it will appear as if the inter- 
rupted system call returned this error condition. 


EIO I/O error 
Some physical I/O error. This error may in some cases occur on a call following the one to which it 
actually applies. 


ENXIO No such device or address 
I/O on a special file refers to a subdevice which does not exist, or beyond the limits of the device. It 
may also occur when, for example, a tape drive is not on-line or no disk pack is loaded on a drive. 


E2BIG Arg list too long 
An argument list longer than 5,120 bytes is presented to a member of the exec family. 


ENOEXEC Exec format error 
A request is made to execute a file which, although it has the appropriate permissions, does not start 
with a valid magic number (see a.out(F)). 


EBADF Bad file number 
Either a file descriptor refers to no open file, or a read (respectively write) request is made to a file 
which is open only for writing (respectively reading). 


ECHILD No child processes 
A wait, was executed by a process that had no existing or unwaited-for child processes. 


EAGAIN No more processes 
A fork, failed because the system’s process table is full or the user is not allowed to create any more 
processes. 


ENOMEM Not enough space 

During an exec, or sbrk, a program asks for more space than the system is able to supply. This is 
not a temporary condition; the maximum space size is a system parameter. The error may also 
occur if the arrangement of text, data, and stack segments requires too many segmentation registers, 
or if there is not enough swap space during a fork. 


EACCES Permission denied 
An attempt was made to access a file in a way forbidden by the protection system. 


EFAULT Bad address 
The system encountered a hardware fault in attempting to use an argument of a system call. 


ENOTBLK Block device required 
A nonblock file was mentioned where a block device was required, e.g., in mount. 


EBUSY Device busy 

An attempt to mount a device that was already mounted or an attempt was made to dismount a 
device on which there is an active file (open file, current directory, mounted-on file, active text seg- 
ment). It will also occur if an attempt is made to enable accounting when it is already enabled. 


EEXIST File exists 
An existing file was mentioned in an inappropriate context, e.g., link. 


EXDEV Cross-device link 
A link to a file on another device was attempted. 
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19 


20 


21 


22 


23 


24 


2) 


26 


ae 


28 


29 


30 


31 


32 


33 


34 


35 


ENODEV No such device 
An attempt was made to apply an inappropriate system call to a device; e.g., read a write-only 
device. 


ENOTDIR Not a directory 
A nondirectory was specified where a directory is required, for example in a path prefix or as an ar- 
gument to chdir(S). 


EISDIR Is a directory 
An attempt to write on a directory. 


EINVAL Invalid argument 

Some invalid argument (e.g., dismounting a nonmounted device; mentioning an undefined signal in 
signal, or kill; reading or writing a file for which /seek has generated a negative pointer). Also set 
by the math functions described in the (S) entries of this manual. 


ENFILE File table overflow 
The system’s table of open files is full, and temporarily no more opens can be accepted. 


EMFILE Too many open files 
No process may have more than 20 file descriptors open at a time. 


ENOTTY Not a typewriter 
The file descriptor that ioct] was handed does not refer to a character special or other device to 
which this call applies. 


ETXTBSY Text file busy 
An attempt to execute a pure-procedure program which is currently open for writing (or reading). 
Also an attempt to open for writing a pure-procedure program that is being executed. 


EFBIG File too large 
The size of a file exceeded the maximum file size (1,082,201,088 bytes) or ULIMIT; see ulimit(S). 


ENOSPC No space left on device 
During a write to an ordinary file, there is no free space left on the device. 


ESPIPE Illegal seek 
An lseek was issued to a pipe. 


EROFS Read-only file system 
An attempt to modify a file or directory was made on a device mounted read-only. 


EMLINK Too many links 
An attempt to make more than the maximum number of links (1000) to a file. 


EPIPE Broken pipe 
A write on a pipe for which there is no process to read the data. This condition normally generates 
a signal; the error is returned if the signal is ignored. 


EDOM Math arg out of domain of func 
The argument of a function in the math package is out of the domain of the function. 


ERANGE Math result not representable 
The value of a function in the math package is not representable within machine precision. 


EUCLEAN File system needs cleaning 
An attempt was made to mount(S) a file system whose super-block is not flagged clean. 


September 7, 1984 Page 3 


INTRO (S) INTRO (S) 


36 EDEADLOCK Would deadlock | 
A process’ attempt to lock a file region would cause a deadlock between processes vying for control 
of that region. 


37 ENOTNAM Not a name file 
A creatsem(S), opensem(S), waitsem(S), or sigsem(S) was issued using an invalid semaphore 
identifier. 


38 ENAVAIL Not available 
An opensem(S), waitsem(S) or sigsem(S) was issued to a semaphore that has not been initialized 
by a call to creatsem(S). A sigsem was issued to a semaphore out of sequence; i.e., before the 
process has issued the corresponding waitsem to the semaphore. An nbwaitsem was issued to a 
semaphore guarding a resource that is currently in use by another process. The semaphore on which 
a process was waiting has been left in an inconsistent state when the process controlling the sema- 
phore exits without relinquishing control properly; i.e., without issuing a waitsem on the semaphore. 


39 EISNAM A name file 
A name file (semaphore, shared data, etc.) was specified when not expected. 


Definitions 
Process ID 


Each active process in the system is uniquely identified by a positive integer called a process ID. The 
range of this ID is from 0 to 30,000. 


Parent Process ID 


A new process is created by a currently active process; see fork(S). The parent process ID of a process 
is the process ID of its creator. 


Process Group ID 


Each active process is a member of a process group that is identified by a positive integer called the 
process group ID. This ID is the process ID of the group leader. This grouping permits the signaling of 
related processes; see kill(S). 


Tty Group ID 


Each active process can be a member of a terminal group that is identified by a positive integer called 
the tty group ID. This grouping is used to terminate a group of related process upon termination of one 
of the processes in the group; see exit(S) and signal(S). 

Real User ID and Real Group ID 


Each user allowed on the system is identified by a positive integer called a real user ID. 


Each user is also a member of a group. The group is identified by a positive integer called the real 
group ID. 


An active process has a real user ID and real group ID that are set to the real user ID and real group ID, 
respectively, of the user responsible for the creation of the process. 
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Effective User ID and Effective Group ID 


An active process has an effective user ID and an effective group ID that are used to determine file 
access permissions (see below). The effective user ID and effective group ID are equal to the process’ 
real user ID and real group ID respectively, unless the process or one of its ancestors evolved from a file 
that had the set-user-ID bit or set-group ID bit set; see exec(S). 


Super-User 


A process is recognized as a super-user process and is granted special privileges if its effective user ID is 
0. 


Special Processes 


The processes with a process ID of 0 and a process ID of | are special processes and are referred to as 
procO and procl. 


ProcO is the scheduler. Proc! is the initialization process (init). Procl is the ancestor of every other 
process in the system and is used to control the process structure. 


Filename 
Names consisting of up to 14 characters may be used to name an ordinary file, special file or directory. 


These characters may be selected from the set of all character values excluding 0 (null) and the ASCII 
code for a / (slash). 


Note that it is generally unwise to use *, ?, [, or ] as part of filenames because of the special meaning at- 
tached to these characters by the shell. Likewise, the high order bit of the character should not be set. 


Pathname and Path Prefix 


A pathname is a null-terminated character string starting with an optional slash (/), followed by zero or 
more directory names separated by slashes, optionally followed by a filename. A filename is a string of 
1 to 14 characters other than the ASCII slash and null, and a directory name is a string of 1 to 14 char- 
acters (other than the ASCII slash and null) naming a directory. 


If a pathname begins with a slash, the path search begins at the root directory. Otherwise, the search 
begins from the current working directory. 


A slash by itself names the root directory. 


Unless specifically stated otherwise, the null pathname is treated as if it named a nonexistent file. 


Directory 


Directory entries are called links. By convention, a directory contains at least two links, . and .., re- 
ferred to as dot and dot-dot respectively. Dot refers to the directory itself and dot-dot refers to its 
parent directory. 
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Root Directory and Current Working Directory 


Each process has associated with it a concept of a root directory and a current working directory for the 
purpose of resolving pathname searches. A process’ root directory need not be the root directory of the 
root file system. See chroot(C) and chroot (S). 


File Access Permissions 


Read, write, and execute/search permissions on a file are granted to a process if one or more of the fol- 
lowing are true: 


The process’ effective user ID is super-user. 


The process’ effective user ID matches the user ID of the owner of the file and the appropriate access 
bit of the “owner’’ portion (0700) of the file mode is set. 


The process’ effective user ID does not match the user ID of the owner of the file, and the process’ 
group ID matches the group of the file and the appropriate access bit of the “group” portion (070) 
of the file mode is set. 


The process’ effective user ID does not match the user ID of the owner of the file, and the process’ 
effective group ID does not match the group ID of the file, and the appropriate access bit of the 
“other” portion (07) of the file mode is set. 


Otherwise, the corresponding permissions are denied. See chmod(C) and chmod(S). 


See Also 


intro(C) 
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Name 


ie a64l, 164a — Converts between long integer and base 64 ASCII. 


Syntax 


long a64l (s) 
char *s; 


char *164a (I) 
long 1; 
Description 


These routines are used to maintain numbers stored in base 64 ASCII. This is a notation by which long 
integers can be represented by up to six characters; each character represents a “digit” in a radix 64 no- 
tation. 


The characters used to represent “digits” are . for 0, / for 1, 0 through 9 for 2 through 11, A through Z 
for 12 through 37, and a through z for 38 through 63. 


A64I takes a pointer to a null-terminated base 64 representation and returns a corresponding long value. 


L64a takes a long argument and returns a pointer to the corresponding base 64 representation. 


Notes 


co The value returned by /64a is a pointer into a static buffer, the contents of which are overwritten by 
each call. 
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Name 


abort — Generates an IOT fault. 


Syntax 


abort ( ) 


Description 


Abort causes an I/O trap signal (SIGIOT) to be sent to the calling process. This usually results in ter- 
mination with a core dump. 


Abort can return control if the calling process is set to catch or ignore the SIGIOT signal; see signal(S). 


See Also 


adb(CP), exit(S), signal(S) 
Diagnostics 


If an aborted process returns control to the shell ( sh(C)), the shell usually displays the message “abort 
— core dumped”’. 
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Name 

abs — Returns an integer absolute value. 
Syntax 

int abs (i) 


int 1; 


Description 


Abs returns the absolute value of its integer operand. 


See Also 


fabs in floor(S) 


Notes 


If the largest negative integer supported by the hardware is given, the function returns it unchanged. 
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Name 


access — Determines accessibility of a file. 


Syntax 


int access (path, amode) 
char «path; 
int amode; 


Description 


Path points to a pathname naming a file. Access checks the named file for accessibility according to the 
bit pattern contained in amode, using the real user ID in place of the effective user ID and the real 
group ID in place of the effective group ID. The bit pattern for amode can be formed by adding any 
combination of the following: 


04 Read 

02 Write 

01 Execute (search) 

00 Check existence of file 


Access to the file is denied if one or more of the following are true: 
A component of the path prefix is not a directory. [ENOTDIR] 
Read, write, or execute (search) permission is requested for a null pathname. [ENOENT] 
The named file does not exist. [ENOENT] 
Search permission is denied on a component of the path prefix. [EACCES] 
Write access is requested for a file on a read-only file system. [EROFS] 
Write access is requested for a pure procedure (shared text) file that is being executed. [ETXTBSY] 
Permission bits of the file mode do not permit the requested access. [EACCES] 
Path points outside the process’ allocated address space. [EFAULT] 


Access checks the permissions for the owner of a file by checking the “owner” read, write, and execute 
mode bits. For members of the file’s group, the “group” mode bits are checked. For all others, the 
“other” mode bits are checked. 

Return Value 
If the requested access is permitted, a value of 0 is returned. Otherwise, a value of —1 is returned and 
errno is set to indicate the error. 


See Also 


chmod(S), stat(S) 
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Notes 


The super-user (root) may access any file, regardless of permission settings. 


June 28, 1985 Page 2 


ACCT (S) ACCT (S) 


Name 


acct — Enables or disables process accounting. 


Syntax 
int acct (path) 
char *path; 
Description 


Acct is used to enable or disable the system’s process accounting routine. If the routine is enabled, an 
accounting record will be written on an accounting file for each process that terminates. A process can 
be terminated by a call to exit or by receipt of a signal which it does not ignore or catch; see exit(S) 
and signal(S). The effective user ID of the calling process must be super-user to use this call. 


Path points to the pathname of the accounting file. The accounting file format is given in acct(F). 


The accounting routine is enabled if path is nonzero and no errors occur during the system call. It is 
disabled if path is zero and no errors occur during the system call. 


Acct will fail if one or more of the following are true: 
The effective user ID of the calling process is not super-user. [EPERM] 
An attempt is being made to enable accounting when it is already enabled. [EBUSY] 
A component of the path prefix is not a directory. [ENOTDIR] 
One or more components of the accounting file’s pathname do not exist. [ENOENT] 
A component of the path prefix denies search permission. [EACCES] 
The file named by path is not an ordinary file. [EACCES] 
Mode permission is denied for the named accounting file. [EACCES] 
The named file is a directory. [EACCES] 
The named file resides on a read-only file system. [EROFS] 


Path points to an illegal address. [EFAULT] 


Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


accton(C), acctcom(C), acct(F) 
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Name 


alarm — Sets a process’ alarm clock. 


Syntax 
unsigned alarm (sec) 
unsigned sec; 
Description 


Alarm sets the calling process’ alarm clock to sec seconds. After sec “real-time” seconds have elasped, 
the alarm clock sends a SIGALRM signal to the process; see signal(S). 


Although alarm does not wait for the signal after setting the alarm clock, pause(S) may be used to 
make the calling process wait. 


Alarm requests are not stacked; successive calls reset the calling process’ alarm clock. 


If sec is 0, any previously made alarm request is canceled. 


Return Value 


Alarm returns the amount of time previously remaining in the calling process’ alarm clock. 


See Also 


pause(S), signal(S) 
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Name 


assert — Helps verify validity of program. 


Syntax 
#include <assert.h> 


assert (expression); 


Description 


This macro is useful for putting diagnostics into programs under development. When it is executed, if 
expression is false, it prints 


Assertion failed: file name, line nnn 


on the standard error file and exits. Name is the source filename and nnn the source line number of the 
assert statement. 


Notes 


To suppress calls to assert, use the option ““-DNDEBUG” when compiling the program; see cc(CP)). 
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Name 


atof, atoi, atol — Converts ASCII to numbers. 


Syntax 


double atof (nptr) 
char *nptr; 


int atoi (nptr) 
char «nptr; 


long atol (nptr) 
char «nptr; 
Description 


These functions convert a string pointed to by nptr to floating, integer, and long integer numbers respec- 
tively. The first unrecognized character ends the string. 


Atof recognizes a string of the form: 
[ +| — ] digits[. digits ][ e| E [ +] — ] digits ] 


where the digits are continguous decimal digits. Any number of tabs and spaces may precede the string. 
The + and — signs are optional. Either e or E may be used to mark the beginning of the exponent. 


Atoi and atol recognize strings of the form: 
[ +| — ] digits 
where the digits are contiguous decimal digits. Any number of tabs and spaces may precede the string. 
The + and — signs are optional. 
See Also 


scanf(S) 


Notes 


There are no provisions for overflow. 
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Name 
a 


bessel, j0, jl, jn, yO, yl, yn — Performs Bessel functions. 


Syntax 
#include <math.h> 


double j0 (x) 
double x; 


double jl (x) 
double x; 


double jn (n, x); 
double x; 


double yO (x) 
double x; 


double y1 (x) 
double x; 


double yn (n, x) 
int n; 
double x; 
i Description 
These functions calculate Bessel functions of the first and second kinds for real arguments and integer 
orders. 
Notes 


Negative arguments cause y0, y/, and yn to return a huge negative value. 
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Name 


bsearch — Performs a binary search. 


Syntax 


char *bsearch (key, base, nel, width, compar) 
char *key; 

char *base; 

int nel, width; 

int (*compar\); 


Description 


Bsearch is a binary search routine generalized from Knuth (6.2.1) Algorithm B. It returns a pointer 
into a table indicating the location at which a datum may be found. The table must be previously sorted 
in increasing order. The first argument is a pointer to the datum to be located in the table. The second 
argument is a pointer to the base of the table. The third is the number of elements in the table. The 
fourth is the width of an element in bytes. The last argument is the name of the comparison routine. It 
is called with two arguments which are pointers to the elements being compared. The routine must re- 
turn an integer less than, equal to, or greater than 0, depending on whether the first argument is to be 
considered less than, equal to, or greater than the second. 


Return Value 


If the key cannot be found in the table, a value of 0 is returned. 


See Also 


lsearch(S), qsort(S) 
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Name 


chdir — Changes the working directory. 


Syntax 


int chdir (path) 
char «path; 


Description 


Path points to the pathname of a directory. Chdir causes the named directory to become the current 
working directory, the starting point for path searches for pathnames not beginning with /. 


Chdir will fail and the current working directory will be unchanged if one or more of the following are 
true: 


A component of the pathname is not a directory. [ENOTDIR] 
The named directory does not exist. [ENOENT] 
Search permission is denied for any component of the pathname. [EACCES] 


Path points outside the process’ allocated address space. [EFAULT] 


Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


chroot(S) 
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Name 


chmod — Changes mode of a file. 


Syntax 


int chmod (path, mode) 
char «path; 
int mode; 


Description 


Path points to a pathname naming a file. Chmod sets the access permission portion of the named file’s 
mode according to the bit pattern contained in mode. 


Access permission bits for mode can be formed by adding any combination of the following: 


04000 Set user ID on execution 

02000 Set group ID on execution 
01000 Save text image after execution 
00400 Read by owner 

00200 Write by owner 

00100 Execute (or search if a directory) by owner 
00040 Read by group 

00020 Write by group 

00010 Execute (or search) by group 
00004 Read by others 

00002 Write by others 

00001 Execute (or search) by others 


To change the mode of a file, the effective user ID of the process must match the owner of the file or 
must be super-user. 


If the effective user ID of the process is not super-user, mode bit 01000 (save text image on execution) is 
cleared. 


If the effective user ID of the process is not super-user or the effective group ID of the process does not 
match the group ID of the file, mode bit 02000 (set group ID on execution) is cleared. 


If an executable file is prepared for sharing, then mode bit 01000 prevents the system from abandoning 
the swap-space image of the program-text portion of the file when its last user terminates. Thus, when 
the next user executes the file, the text need not be read from the file system but can simply be swapped 
in, saving time. Many systems have relatively small amounts of swap space, and the same-text bit 
should be used sparingly, if at all. 


Chmod will fail and the file mode will be unchanged if one or more of the following are true: 
A component of the path prefix is not a directory. [ENOTDIR] 
The named file does not exist. [ENOENT] 
Search permission is denied on a component of the path prefix. [EACCES] 


The effective user ID does not match the owner of the file and the effective user ID is not super-user. 
[EPERM] 
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The named file resides on a read-only file system. [EROFS] 


Path points outside the process’ allocated address space. [EFAULT] 


Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


chown(S), mknod(S) 
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Name 


chown — Changes the owner and group of a file. 


Syntax 
int chown (path, owner, group) 
char *path; 
int owner, group; 


Description 


Path points to a pathname naming a file. The owner ID and group ID of the named file are set to the 
numeric values contained in owner and group respectively. 


Only processes with an effective user ID equal to the file owner or super-user may change the ownership 
of a file. 


If chown is invoked by other than the super-user, the set-user-ID and set-group-ID bits of the file mode, 
04000 and 02000 respectively, will be cleared. 


Chown will fail and the owner and group of the named file will remain unchanged if one or more of the 
following are true: 


A component of the path prefix is not a directory. [ENOTDIR] 
The named file does not exist. [ENOENT] 
Search permission is denied on a component of the path prefix. [EACCES] 


The effective user ID does not match the owner of the file, and the effective user ID is not super- 
user. [EPERM] 


The named file resides on a read-only file system. [EROFS] 


Path points outside the process’ allocated address space. [EFAULT] 


Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


chmod(S) 


June 28, 1985 Page 1 


CHROOT (S) CHROOT (S) 


Name 


chroot — Changes the root directory. 


Syntax 


int chroot (path) 
char «path; 


Description 


Path points to a pathname naming a directory. Chroot causes the named directory to become the root 
directory, the starting point for path searches for pathnames beginning with /. 


To change the root directory, the effective user ID of the process must be super-user. 


6e 699 


The “‘..” entry in the root directory is interpreted to mean the root directory itself. Thus, “..”’ cannot be 
used to access files outside the root directory. 


Chroot will fail and the root directory will remain unchanged if one or more of the following are true: 
Any component of the pathname is not a directory. [ENOTDIR] 
The named directory does not exist. [ENOENT] 
The effective user ID is not super-user. [EPERM] 


Path points outside the process’ allocated address space. [EFAULT] 


Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


chdir(S), chroot(C) 
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Name 


chsize — Changes the size of a file. 


Syntax 


int chsize (fildes, size) 
int fildes; 
long size; 

Description 


Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system call. Chsize changes 
the size of the file associated with the file descriptor fildes to be exactly size bytes in length. The 
routine either truncates the file, or pads it with an appropriate number of bytes. If size is less than the 
initial size of the file, then all allocated disk blocks between size and the initial file size are freed. 


The maximum file size as set by ulimit (S) is enforced when chsize is called, rather than on subsequent 
writes. Thus chsize fails, and the file size remains unchanged if the new changed file size would exceed 
the ulimit. 


Return Value 
Upon successful completion, a value of 0 is returned. Otherwise, the value —1 is returned and errno is 
set to indicate the error. 

See Also 


creat(S), dup(S), lseek(S), open(S), pipe(S), ulimit(S) 


Notes 


In general if chsize is used to expand the size of a file, when data is written to the end of the file, in- 
tervening blocks are filled with zeros. In a few rare cases, reducing the file size may not remove the data 
beyond the new end-of-file. This routine may be linked with the linker option - Ix. 
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Name 


close — Closes a file descriptor. 


Syntax 
int close (fildes) 
int fildes; 
Description 


Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system call. Close closes the 
file descriptor indicated by /fildes. 


Close will fail if fildes is not a valid open file descriptor. [EBADF] 


Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


creat(S), dup(S), exec(S), fentl(S), open(S), pipe(S) 
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Name 


‘a 


conv, toupper, tolower, toascii — Translates characters. 


Syntax 
#include <ctype.h> 


int toupper (c) 
int c; 


int tolower (c) 
int c; 


int toupper (c) 
int ¢c; 


int tolower (c) 
int ¢c; 


int toascii (c) 
int ¢; 
Description 


Toupper and tolower convert the argument c to a letter of opposite case. Arguments may be the in- 
tegers —1 through 255 (the same values returned by getc(S)). If the argument of toupper represents a 


f~ lowercase letter, the result is the corresponding uppercase letter. If the argument of tolower represents 
an uppercase letter, the result is the corresponding lowercase letter. All other arguments are returned 
unchanged. 


_toupper and _tolower are macros that accomplish the same thing as toupper and tolower but have res- 
tricted argument values and are faster. _toupper requires a lowercase letter as its argument; its result is 
the corresponding uppercase letter. _tolower requires an uppercase letter as its argument; its result is 
the corresponding lowercase letter. All other arguments cause unpredictable results. 


Toascii converts integer values to ASCII characters. The function clears all bits of the integer that are 


not part of a standard ASCII character; it is intended for compatibility with other systems. 


See Also 


ctype(S) 


Notes 


Because toupper and tolower are implemented as macros, they should not be used where unwanted 
side effects may occur. Removing the toupper and tolower macros with the #undef directive causes 
the corresponding library functions to be linked instead. This allows any arguments to be used without 
worry about side effects. 
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Name 


creat — Creates a new file or rewrites an existing one. 


Syntax 


int creat (path, mode) 
char *path; 
int mode; 


Description 


Creat creates a new ordinary file or prepares to rewrite an existing file named by the pathname pointed 
to by path. 


If the file exists, the length is truncated to 0 and the mode and owner are unchanged. Otherwise, the 
file’s owner ID is set to the process’ effective user ID, the file’s group ID is set to the process’ effective 
group ID, and the access permission bits (i.e., the low-order 12 bits of the file mode) are set to the value 
of mode. Mode may has the same values as described for chmod(S). Creat will then modify the access 
permission bits as follows: 


All bits set in the process’ file mode creation mask are cleared. See umask(S). 
The “‘save text image after execution bit” is cleared. See chmod(S). 


Upon successful completion, a nonnegative integer, namely the file descriptor, is returned and the file is 
open for writing, even if the mode does not permit writing. The file pointer is set to the beginning of the 
file. The file descriptor is set to remain open across exec system calls. See fcentl(S). No process may 
have more than 20 files open simultaneously. A new file may be created with a mode that forbids wri- 
ting. 


Creat will fail if one or more of the following are true: 
A component of the path prefix is not a directory. [ENOTDIR] 
A component of the path prefix does not exist. [ENOENT] 
Search permission is denied on a component of the path prefix. [EACCES] 
The pathname is null. [ENOENT] 


The file does not exist and the directory in which the file is to be created does not permit writing. 
[EACCES] 


The named file resides or would reside on a read-only file system. [EROFS] 

The file is a pure procedure (shared text) file that is being executed. [ETXTBSY] 
The file exists and write permission is denied. [EACCES] 

The named file is an existing directory. [EISDIR] 

Twenty file descriptors are currently open. [EMFILE] 


Path points outside the process’ allocated address space. [EFAULT] 
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Return Value 
Upon successful completion, a nonnegative integer, namely the file descriptor, is returned. Otherwise, a a, 
value of —1 is returned and errno is set to indicate the error. 

See Also 


close(S), dup(S), Iseek(S), open(S), read(S), umask(S), write(S) 


Notes 


Open(S) is preferred to creat. 
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Name 


creatsem — Creates an instance of a binary semaphore. 


Syntax 


sem num = creatsem(sem_name,mode); 
int sem_num,mode 
char *sem_ name; 


Description 


Creatsem defines a binary semaphore named by sem_name to be used by waitsem(S) and sigsem(S) to 
manage mutually exclusive access to a resource, shared variable, or critical section of a program. 
Creatsem returns a unique semaphore number sem_num which may then be used as the parameter in 
waitsem and sigsem calls. Semaphores are special files of 0 length. The filename space is used to pro- 
vide unique identifiers for semaphores. Mode sets the accessibility of the semaphore using the same 
format as file access bits. Access to a semaphore is granted only on the basis of the read access bit; the 
write and execute bits are ignored. 


A semaphore can be operated on only by a synchronizing primitive, such as waitsem or sigsem, by 
creatsem which initializes it to some value, or by opensem which opens the semaphore for use by a 
process. Synchronizing primitives are guaranteed to be executed without interruption once started. 
These primitives are used by associating a semaphore with each resource (including critical code sec- 
tions) to be protected. 


The process controlling the semaphore should issue 
sem_ num = creatsem("semaphore", mode); 


to create, initialize, and open the semaphore for that process. All other processes using the semaphore 
should issue 


sem_num = opensem("semaphore") 


to access the semaphore’s identification value. Note that a process cannot open and use a semaphore 
that has not been initialized by a call to creatsem, nor should a process open a semaphore more than 
once in one period of execution. Both the creating and opening processes use waitsem and sigsem to use 
the semaphore sem_num. 


Notes 
After a creatsem you must do a waitsem to gain control of a given resource. 


This feature is a XENIX specific enhancement and may not be present in all UNIX implementations. 
This function may be linked with the linker option - Ix. 


Diagnostics 


Creatsem returns the value —1 if an error occurs. If the semaphore named by sem_name is already open 
for use by other processes, errno is set to EEXIST. If the file specified exists but is not a semaphore type, 
errno is set to ENOTNAM. If the semaphore has not been initialized by a call to creatsem, errno is set 
to ENAVAIL. 
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See Also 


opensem(S), waitsem(S), sigsem(S). 
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Name 


ry 


crypt, setkey, encrypt — Performs encryption functions. 


Syntax 


char «crypt (key, salt) 
char «key, «salt; 


setkey (key) 
char *key; 


encrypt (block, edflag) 
char *block; 
int edflag; 


Description 


Crypt is the password encryption routine. It is based on the NBS Data Encryption Standard (DES), 
with variations intended (among other things) to frustrate use of hardware implementations of the DES 
for key search. 


The first argument to crypt is a user’s typed password. The second is a 2-character string chosen from 
the set [a-zA-Z0-9./]; this salt string is used to perturb the DES algorithm in one of 4096 different 
ways, after which the password is used as the key to encrypt repeatedly a constant string. The returned 
value points to the encrypted password, in the same alphabet as the salt. The first two characters are 
the salt itself. 


The setkey and encrypt entries provide access to the actual DES algorithm. The argument of setkey is a 
character array of length 64 containing only the characters with numerical value 0 and 1. If this string 
is divided into groups of 8, the low-order bit in each group is ignored, leading to a 56-bit key which is 
set into the machine. 


The argument to the encrypt entry is likewise a character array of length 64 containing zeroes and ones. 
The argument array is modified in place to a similar array representing the bits of the argument after 
having been subjected to the DES algorithm using the key set by setkey. If edflag is 0, the argument is 
encrypted; if nonzero, it is decrypted. 


See Also 


passwd(C), getpass(S), passwd(M) 


Notes 


The return value from crypt points to static data that is overwritten by each call. 
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Name 


ctermid — Generates a filename for a terminal. 


Syntax 
#include <stdio.h> 
char *ctermid(s) 
char *s; 
Description 


Ctermid returns a pointer to a string that, when used used as a filename, refers to the controlling ter- 
minal of the calling process. 


If (int)s is zero, the string is stored in an internal static area, the contents of which are overwritten at 
the next call to ctermid, and the address of which is returned. If (int)s is nonzero, then s is assumed to 
point to a character array of at least L_ctermid elements; the string is placed in this array and the value 
of s is returned. The manifest constant L_ctermid is defined in <stdio.h>. 


Notes 


The difference between ctermid and ttyname(S) is that ttyname must be given a file descriptor and it 
returns the actual name of the terminal associated with that file descriptor, while ctermid returns a 
magic string (/dev/tty) that will refer to the terminal if used as a filename. Thus ttyname is useless 
unless the process already has at least one file open to a terminal. 


See Also 


ttyname(S) 
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Name 


ctime, localtime, gmtime, asctime, tzset — Converts date and time to ASCII. 


Syntax 


char *ctime (clock) 
long «clock; 


#include <time.h> 


struct tm *localtime (clock) 
long «clock; 


struct tm *gmtime (clock) 
long «clock; 


char *asctime (tm) 
struct tm *tm; 


tzset ( ) 


extern long timezone; 
extern int daylight; 
extern char tzname; 


Description 


Ctime converts a time pointed to by clock (such as returned by time(S)) into ASCII and returns a 
pointer to a 26-character string in the following form: 


Sun Sep 16 01:03:52 1973\n\0 
If necessary, fields in this string are padded with spaces to keep the string a constant length. 


Localtime and gmtime return pointers to structures containing the time as a variety of individual quan- 
tities. These quantities give the time on a 24-hour clock, day of month (1-31), month of year (0-11), 
day of week (Sunday = 0), year (since 1900), day of year (0-365), and a flag that is nonzero if daylight 
saving time is in effect. Localtime corrects for the time zone and possible daylight savings time. 
Gmtime converts directly to Greenwich time (GMT), which is the time the XENIX system uses. 


Asctime converts the times returned by localtime and gmtime to a 26-character ASCII string and re- 
turns a pointer to this string. 


The structure declaration for tm is defined in /usr/include/time.h. 


The external long variable timezone contains the difference, in seconds, between GMT and local stan- 
dard time (e.g., in Eastern Standard Time (EST), timezone is 5*60*60); the external integer variable 
daylight is nonzero if and only if the standard U.S.A. Daylight Savings Time conversion should be ap- 
plied. The program knows about the peculiarities of this conversion in 1974 and 1975. 


If an environment variable named TZ is present, asctime uses the contents of the variable to override the 
default time zone. The value of TZ must be a three-letter time zone name, followed by a number 
representing the difference between local time (with optional sign) and Greenwich time in hours, fol- 
lowed by an optional three-letter name for a daylight time zone. For example, the setting for New 
Jersey would be ESTSEDT. The effects of setting TZ are thus to change the values of the external vari- 
ables timezone and daylight. In addition, the time zone names contained in the external variable 
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char *tzname[2] = {"EST", "EDT"}; 


are set from the environment variable. The function tzset sets the external variables from TZ ; it is Sg 
called by asctime and may also be called explicitly by the user. 


See Also 


time(S), getenv(S), environ(M) 


Notes 


The return values point to static data those content is overwritten by each call. 
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Name 
Oo 


ctype, isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, isgraph, iscntrl, isascii 
— Classifies characters. 

Syntax 
#include <ctype.h> 


int isalpha (c) 
int ¢; 


Description 


These macros classify ASCII-coded integer values by table lookup. Each returns nonzero for true, zero 
for false. Isascii is defined on all integer values; the rest are defined only where isascii is true and on 
the single non-ASCII value EOF (see stdio(S)). 


isalpha c is a letter 
isupper c is an uppercase letter 
islower c is a lowercase letter 
lan isdigit c is a digit [0-9] 

| isxdigit c is a hexidecimal digit [0-9], [A-F] or [a-f] 
isalnum c is an alphanumeric 
isspace c is a space, tab, carriage return, newline, vertical tab, or form feed 
ispunct c is a punctuation character (neither control nor alphanumeric) 
isprint c is a printing character, octal 40 (space) through octal 176 (tilde) 
isgraph c is a printing character, like isprint except false for space 
iscntrl c is a delete character (octal 177) or ordinary control character (less than octal 40). 
isascii c is an ASCII character, code less than 0200 

See Also 

ascii(M) 
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Name 


curses — Performs screen and cursor functions. 


Syntax 


#include <curses.h> 
WINDOW *curscr, *stdscr; 


Description 


These routines give the user a method of updating screens with reasonable optimization. They keep an 
image of the current screen, curscr, and the user modifies this image by modifying the standard screen, 
stdscr, or by setting up a new screen. The refresh and wrefresh routines make the current screen look 
like the modified one. In order to initialize the routines, the routine initscr must be called before any of 
the other routines that deal with windows and screens are used. 


The routines are linked with the linker options —Icurses and —Itermcap. 


Functions 


int addch(ch) 
char ch; 
Adds a character to stdscr 


int addstr(str) 
char *str; 
Adds a string to stdscr 


int box(win,vert,hor) 
WINDOW *win; 
char vert, hor; 
Draws a box around a window 


int crmode() 
Sets cbreak mode 


int clear() 
Clears stdscr 


int clearok(win,state) 
WINDOW *win; 
bool state; 
Sets clear flag for win 


int clrtobot() 
Clears to bottom on stdscr 


int clrtoeol() 
Clears to end of line on stdscr 


int delch() 
Deletes character from stdscr 
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int deleteln() 
Deletes line from stdscr 


int delwin(win) 
WINDOW *win; 
Delete win 


int echo() 
Sets echo mode 


int erase() 
Erase stdscr 


int getch() 
Gets a char through stdscr 


int getstr(str) 
char *str; 
Gets a string through stdser 


int gettmode() 
Gets tty modes 


int getyx(win,y,x) 
WINDOW *win; 
int (y,x); 
Gets current (y,x) position of win 


int inch() 
Gets char at current (y,x) co-ordinates 


WINDOW “Finitscr() 
Initializes screens 


int insch(c) 
char c; 
Inserts character in stdscr 


int insertln() 
Inserts blank line in stdscr 


int leaveok(win,state) 
WINDOW *win; 
bool state; 
Sets leave flag for win 


int longname(termbuf,name) 
char *termbuf, *name; 
Gets long name from termbuf 


int move(y,x) 
int y,x; 
Moves to (y,x) on stdser 


int mvaddch(y,x,ch) 
int y,x; 
char ch; 
Moves to (y,x) and adds character 
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ch 
int mvaddstr(y,x,str) 
int y,x; 
char *str; 


Moves to (y,x) and adds string 
Str 


int mycur(lasty,lastx,newy,newx) 

int lasty, lastx, newy, newx; 
Moves cursor the from (lasty,lastx) 
to (newy,newx) 


int mvdelch(y,x) 

int y,x; 
Moves to (y,x) and deletes 
character from stdscr 


int mygetch(y,x) 

int y,x; 
Moves to (y,x) and gets a char 
through stdser 


int mvgetstr(y,x,str) 

int y,x; 

char *str; 
Moves to (y,x) and gets a string 
through stdser 


int mvinch(y,x) 

int y,x; 
Moves to (y,x) and gets char at 
current co-ordinates 


int mvinsch(y,x,c) 

int y,x; 

char ¢; 
Moves to (y,x) and inserts 
character in stdscr 


int mywaddch(win, y,x,ch) 

WINDOW *win; 

int y,x; 

char ch; 
Moves to (y,x) in win and 
adds character ch 


int mywaddstr(win,y,x,str) 

WINDOW *win; 

int y,x; 

char *str; 
Moves to (y,x) in win 
and adds string str 


int mvwdelch(win,y,x) 


WINDOW *win; 
int y,x; 
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Moves to (y,x) in win 
and deletes the character 


int mywgetch(win,y,x) 

WINDOW *win; 

int y,x; 
Moves to (y,x) in win and 
gets a character 


int mywgetstr(y,x,str) 

WINDOW *win; 

int y,x; 

char *str; 
Moves to (y,x) in win 
and gets a string 


int mvwin(win,y,x) 
WINDOW *win; 
int y,x; 
Moves upper corner of win to (y,x) 


int mywinch(win,y,x) 
WINDOW *win; 
int y,x; 
Moves to (y,x) in win and 
gets character at current co-ordinates 


int mywinsch(win,y,x,c) 

WINDOW *win; 

int y,x; 

char c; 
Moves to (y,x) in win and 
inserts character 


WINDOW *newwin(lines,cols,begin y,begin x) 
int lines, cols, bigin y, begin x; 
Creates a new window 


int nl() 
Sets newline mapping 


int nocrmode() 
Unsets cbreak mode 


int noecho() 
Unsets echo mode 


int nonl() 
Unsets newline mapping 


int noraw() 
Unsets raw mode 


int overlay(win1,win2) 


WINDOW *winl, *win2; 
Overlays winl on win2 
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int overwrite(win1l,win2) 
WINDOW *winl, *win2; 
Overwrites win] on top of win2 


int printw(fmt,arg1,arg2.,...) 
char *fmt; 
Prints args on stdscr 


int raw() 
Sets raw mode 


int refresh() 
Makes current screen look like stdscr 


int restty() 
Resets tty flags to stored value 


int savetty() 
Stored current tty flags 


int scanw(fmt,arg1,arg2,...) 
char *fmt; 
Scans for args through stdser 


int scroll(win) 
WINDOW *win; 
Scrolls win one line 


int scrollok(win,state) 
WINDOW *win; 
bool state; 

Sets scroll flag 


int setterm(name) 
char *name; 
Sets term variables for name 


int standend() 
Clears standout mode of stdscr 


int standout() 
Sets standout mode for characters in subsequent 
Output to stdscr 


WINDOW ‘*subwin(win,lines,cols,begin y,begin x) 
WINDOW *win; 
int lines, cols, begin y, begin x; 

Creates a subwindow in win 


int touchwin(win) 

WINDOW *win; 
Prepares win for complete update on 
next refresh. 


int unctri(ch) 
char ch; 
Printable version of ch 
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int waddch(win,ch) 
WINDOW *win; 
char ch; 
Adds char to win 


int waddstr(win,str) 
WINDOW *win; 
char *str; 
Adds string to win 


int wclear(win) 
WINDOW *win; 
Clear win 


int wclrtobot(win) 
WINDOW *win; 
Clears to bottom of win 


int welrtoeol(win) 
WINDOW ‘win; 
Clears to end of line on win 


int wdelch(win) 
WINDOW *win; 
Deletes current character from win 


int wdeleteln(win) 
WINDOW *win; 
Deletes line from win 


int werase(win) 
WINDOW *win; 
Erase win 


int wgetch(win) 
WINDOW *win; 
Gets a char through win 


int wgetstr(win,str) 
WINDOW *win; 
char *str; 
Gets a string through win 


int winch(win) 
WINDOW *win; 
Gets char at current (y,x) in win 


int winsch(win,c) 
WINDOW *win; 
char ¢c; 
Inserts character c in win 


int winsertln(win) 


WINDOW *win; 
Inserts a blank line in win 
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int wmove(win,y,x) 
WINDOW *win; 
int y,x; 
Sets current (y,x) co-ordinates on 


int wprintw(win,fmt,arg1,argz2,...) 
WINDOW *win; 
char *fmt; 

Print args on win 


int wrefresh(win) 
WINDOW *win; 
Makes screen look like win 


int wscanw(win,fmt,arg1,arg2....) 
WINDOW *win; 
char *fmt; 
Scans for args through win 


int wstandend(win) 
WINDOW *win; 
Clears standout mode for win 
int wstandout(win) 
WINDOW *win; 
Sets standout mode for characters on 
subsequent output to win 
See Also 
termcap(M), stty(C), setenv(S) 
XENIX Library Guide 
Credit 


This utility was developed at the University of California at Berkeley and is used with permission. 
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Name 


cuserid — Gets the login name of the user. 


Syntax 
#include <stdio.h> 
char «cuserid (s) 
char *s; 
Description 


Cuserid returns a pointer to string which represents the login name of the owner of the current process. 
If (int)s is zero, this representation is generated in an internal static area, the address of which is re- 
turned. If (int)s is nonzero, s is assumed to point to an array of at least L_cuserid characters; the 
representation is left in this array. The manifest constant L_cuserid is defined in <stdio.h>. 


Diagnostics 
If the login name cannot be found, cuserid returns NULL; if s is nonzero in this case, \0 will be placed 
at *S. 

See Also 


getlogin(S), getpwent in getpwent(S) 


Notes 


Cuserid uses getpwnam (see getpwent(S)); thus the results of a user’s call to the latter will be obli- 
terated by a subsequent call to the former. 
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Name 


dbminit, fetch, store, delete, firstkey, nextkey — Performs database functions. 


Syntax 


typedef struct { char *dptr; int dsize; } datum; 


dbminit(file) 
char *file; 


datum fetch(key) 
datum key; 


store(key, content) 
datum key, content; 


delete(key) 
datum key; 


datum firstkey(); 


datum nextkey(key); 
datum key; 


Description 


These functions maintain key/content pairs in a database. The functions will handle very large (a bil- 
lion blocks) databases and will access a keyed item in one or two file system accesses. The functions are 
obtained with the loader option —Idbm. 


Keys and contents are described by the datum typedef. A datum specifies a string of dsize bytes 
pointed to by dptr. Arbitrary binary data, as well as normal ASCII strings, are allowed. The database is 
stored in two files. One file is a directory containing a bit map and has “dir” as its suffix. The second 
file contains all data and has “.pag”’ as its suffix. 


Before a database can be accessed, it must be opened by dbminit. At the time of this call, the files 
file.dir and file.pag must exist. (An empty database is created by creating zero-length “.dir” and 
** pag’’ files.) 


Once open, the data stored under a key is accessed by fetch and data is placed under a key by store. A 
key (and its associated contents) is deleted by delete. A linear pass through all keys in a database may 
be made, in an (apparently) random order, by use of firstkey and nextkey. Firstkey will return the first 
key in the database. With any key nextkey will return the next key in the database. This code will 
traverse the database: 


for(key=firstkey(); key.dptr!=NULL; key=nextkey(key)) 


Diagnostics 


All functions that return an int indicate errors with negative values. A zero return indicates ok. Rou- 
tines that return a datum indicate errors with a null (0) dptr. 


Notes 
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The “.pag”’ file will contain holes so that its apparent size is about four times its actual content. Older 
XENIX systems may create real file blocks for these holes when touched. These files cannot be copied 
by normal means (cp, cat, tp, tar, ar) without filling in the holes. 


Dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. 


The sum of the sizes of a key/content pair must not exceed the internal block size (currently 512 bytes). 
Moreover all key/content pairs that hash together must fit on a single block. Store will return an error 
in the event that a disk block fills with inseparable data. 


Delete does not physically reclaim file space, although it does make it available for reuse. 
The order of keys presented by firstkey and nextkey depends on a hashing function. 


These routines are not reentrant, so they should not be used on more than one database at a time. 


Credit 


This utility was developed at the University of California at Berkeley and is used with permission. 
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Name 


defopen, defread — Reads default entries. 


Syntax 


int defopen(filename) 
char *filename; 


char *defread(pattern) 
char *pattern; 
Description 


Defopen and defread are a pair of routines designed to allow easy access to default definition files. 
XENIX is normally distributed in binary form; the use of default files allows OEMS or site administra- 
tors to customize utility defaults without having the source code. 


Defopen opens the default file named by the pathname in filename. Defopen returns null if it is suc- 
cessful in opening the file, or the fopen failure code (errno) if the open fails. 


Defread reads the previously opened file from the beginning until it encounters a line beginning with 
pattern. Defread then returns a pointer to the first character in the line after the initial pattern. If a 
trailing newline character is read it is replaced by a null byte. 


When all items of interest have been extracted from the opened file the program may call defopen with 
the name of another file to be searched, or it may call defopen with NULL, which closes the default file 
without opening another. 

Files 
The XENIX convention is for a system program xyz to store its defaults (if any) in the file 
/etc/default /xyz. 

Diagnostics 


Defopen returns zero on success and nonzero if the open fails. The return value is the errno value set by 
fopen(S). 


Defread returns NULL if a default file is not open, if the indicated pattern could not be found, or if it 
encounters any line in the file greater than the maximum length of 128 characters. 
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Name 


dup, dup2 — Duplicates an open file descriptor. 


Syntax 


int dup (fildes) 
int fildes; 


dup2(fildes, fildes2) 
int fildes, fildes2; 
Description 


Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system call. Dup returns a 
new file descriptor having the following in common with the original: 


Same open file (or pipe). 
Same file pointer (i.e., both file descriptors share one file pointer). 
Same access mode (read, write or read/write). 
The new file descriptor is set to remain open across exec system calls. See fentl(S). 


Dup returns the lowest available file descriptor. Dup2 causes fildes2 to refer to the same file as fildes. If 
fildes2 already referred to an open file, it is closed first. 


Dup will fail if one or more of the following are true: 
Fildes is not a valid open file descriptor. [EBADF] 


Twenty file descriptors are currently open. [EMFILE] 


Return Value 
Upon successful completion a nonnegative integer, namely the file descriptor, is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

See Also 


creat(S), close(S), exec(S), fentl(S), open(S), pipe(S) 
Notes 


Dup2 is a XENIX specific enhancement which may not be present in all UNIX implementations. This 
function may be linked with the linker option —Ix. | 
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Name 


cy 


ecvt, fevt, gcvt — Performs output conversions. 


Syntax 
char *ecvt (value, ndigit, decpt, sign) 
double value; 
int ndigit, «decpt, «sign; 
char *fcvt (value, ndigit, decpt, sign) 
double value; 


int ndigit, «decpt, «sign; 


char *gcvt (value, ndigit, buf) 
double value; 
char «buf; 


Description 


Ecvt converts the value to a null-terminated string of ndigit ASCII digits and returns a pointer to the 
string. The position of the decimal point relative to the beginning of the string is stored indirectly 
through decpt (negative means to the left of the returned digits). If the sign of the result is negative, 
the word pointed to by sign is nonzero, otherwise it is zero. The low-order digit is rounded. 


Fcvt is identical to ecvt, except that the correct digit has been rounded for FORTRAN F format output 
a of the number of digits specified by ndigits. 


Gcvt converts the value to a null-terminated ASCII string in buf and returns a pointer to buf. It at- 
tempts to produce ndigit significant digits in FORTRAN F format if possible, otherwise E format, 
ready for printing. Trailing zeros may be suppressed. 


See Also 


printf(S) 


Notes 


The return values point to static data whose content is overwritten by each call. 
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Name 


end, etext, edata — Last locations in program. 


Syntax 


extern char end; 
extern char etext(); 
extern char edata; 


Description 


These names refer neither to routines nor to locations with interesting contents. The address of etext is 
the first address above the program text, edata is the first address above the initialized data region, and 
end is the first address above the uninitialized data region. 


See Also 


brk(S), malloc(S). 


Warning 


No assumptions should be made with respect to the ordering of the program text, initialized data, and 
uninitialized data regions. For example, the assumption can’t be made that the addresses following the 
address of etext will reference the uninitialized data region. 


No assumptions can be made concerning the contiguity of information within a region. A region may be 
split among different parts of memory. Therefore, no assurance can be made that addresses within a re- 
gion are consecutive. 
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Name 


execl, execv, execle, execve, execlp, execvp — Executes a file. 


Syntax 


int execl (path, arg0, arg], ..., argn, 0) 
char *path, *arg0, *arg], ..., *argn; 


int execv (path, argv) 
char «path, *argy{ |; 


int execle (path, arg0, arg], ..., argn, 0, envp) 
char «path, *arg0, «argl, ..., *argn, *envp| |; 


int execve (path, argv, envp); 
char *path, «argy[ ], *envp| ]; 


int execlp (file, arg0, arg], ..., argn, 0) 
char *file, «arg0, *arg1, ..., *argn; 


int execvp (file, argv) 
char *file, «argy{ |; 


Description 


Exec in all its forms transforms the calling process into a new process. The new process is constructed 
from an ordinary, executable file called the “new process file’ . There can be no return from a suc- 
cessful exec because the calling process is overlaid by the new process. 


Path points to a pathname that identifies the new process file. 


File points to the new process file. The path prefix for this file is obtained by a search of the directories 
passed as the environment line “PATH =” (see environ(M)). The environment is supplied by the shell 
(see sh(C)). 


Arg0, argl, ..., argn are pointers to null-terminated character strings. These strings constitute the argu- 
ment list available to the new process. By convention, at least arg0 must be present, and it must point 
to a string that is the same as path (or its last component). 


Argyv is an array of character pointers to null-terminated strings. These strings constitute the argument 
list available to the new process. By convention, argv must have at least one member, and it must point 
to a string that is the same as path (or its last component). Argv is terminated by a null pointer. 


Envp is an array of character pointers to null-terminated strings. These strings constitute the environ- 
ment for the new process. Envp is terminated by a null pointer. 


File descriptors open in the calling process remain open in the new process, except for those whose 
close-on-exec flag is set; see fent/(S). For those file descriptors that remain open, the file pointer is un- 
changed. 


Signals set to terminate the calling process will be set to terminate the new process. Signals set to be ig- 
nored by the calling process will be set to be ignored by the new process. Signals set to be caught by the 
calling process will be set to terminate new process; see signal(S). 
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If the set-user-ID mode bit of the new process file is set (see chmod(S)), exec sets the effective user ID 

of the new process to the owner ID of the new process file. Similarly, if the set-group-ID mode bit of the i, 
new process file is set, the effective group ID of the new process is set to the group ID of the new process 

file. The real user ID and real group ID of the new process remain the same as those of the calling 

process. 


Profiling is disabled for the new process; see profil(S). 
The new process also inherits the following attributes from the calling process: 

Nice value (see nice(S)) 

Process ID 

Parent process ID 

Process group ID 

tty group ID (see exit(S) and signal(S)) 

Trace flag (see ptrace(S) request 0) 

Time left until an alarm clock signal (see alarm(S)) 

Current working directory 

Root directory 

File mode creation mask (see umask(S)) 

File size limit (see ulimit(S)) 

utime, stime, cutime, and cstime (see times(S)) 


From C, two interfaces are available. Execl is useful when a known file with known arguments is being 
called; the arguments to exec/ are the character strings constituting the file and the arguments. The 
first argument is conventionally the same as the filename (or its last component). A 0 argument must 
end the argument list. 


The execv version is useful when the number of arguments is unknown in advance. The arguments to 
execv are the name of the file to be executed and a vector of strings containing the arguments. The last 
argument string must be followed by a 0 pointer. 


When a C program is executed, it is called as follows: 


main(argc, argv, envp) 
int argc; 
char **arev, **enyp: 


where argc is the argument count and argv is an array of character pointers to the arguments them- 
selves. As indicated, argc is conventionally at least one and the first member of the array points to a 
string containing the name of the file. 


Argy is directly usable in another execv because argv[argc] is 0. 


Envp is a pointer to an array of strings that constitute the environment of the process. Each string con- 
sists of a name, an “=”, and a null-terminated value. The array of pointers is terminated by a null J 
pointer. The shell sh(C) passes an environment entry for each global shell variable defined when the 
program is called. See environ(M) for some conventionally used names. The C run-time start-off 
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routine places a copy of envp in the global cell environ, which is used by execv and execl to pass the en- 
vironment to any subprograms executed by the current program. The exec routines use lower-level rou- 
tines as follows to pass an environment explicitly: 


execle(file, arg0, argl,..., argn, 0, environ); 
execve(file, argv, environ); 


Execlp and execvp are called with the same arguments as execl and execv, but duplicate the shell’s ac- 
tions in searching for an executable file in a list of directories. The directory list is obtained from the 
environment. 


Exec will fail and return to the calling process if one or more of the following are true: 
One or more components of the new process file’s pathname do not exist. [ENOENT] 
A component of the new process file’s path prefix is not a directory. [ENOTDIR] 
Search permission is denied for a directory listed in the new process file’s path prefix. [EACCES] 
The new process file is not an ordinary file. [EACCES] 
The new process file mode denies execution permission. [EACCES] 


The new process file has the appropriate access permission, but has an invalid magic number in its 
header. [ENOEXEC] 


The new process file is a pure procedure (shared text) file that is currently open for writing by some 
process. [ETXTBSY] 


The new process requires more memory than is allowed by the system-imposed maximum. 
[ENOMEM] 


The number of bytes in the new process’ argument list is greater than the system-imposed limit of 
5120 bytes. [E2BIG] 


The new process file is not as long as indicated by the size values in its header. [EFAULT] 


Path, argv, or envp point to an illegal address. [EFAULT] 


Return Value 


If exec returns to the calling process an error has occurred; the return value will be —1 and errno will be 
set to indicate the error. 


See Also 


exit(S), fork(S) 
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Name 


exit — Terminates a process. 


Syntax 
exit (status) 
int status; 
Description 
Exit terminates the calling process. All of the file descriptors open in the calling process are closed. 


If the parent process of the calling process is executing a wait, it is notified of the calling process’ ter- 
mination and the low-order 8 bits (i.e., bits 0377) of status are made available to it; see wait(S). 


If the parent process of the calling process is not executing a wait, the calling process is transformed 
into a “zombie process.” A zombie process is a process that only occupies a slot in the process table, it 
has no other space allocated either in user or kernel space. The process table slot that it occupies is par- 
tially overlaid with time accounting information (see <sys/proc.h>) to be used by times(S). 


The parent process ID of all of the calling process’ existing child processes and zombie processes is set 
to 1. This means the initialization process (see intro(S)) inherits each of these processes. 


An accounting record is written on the accounting file if the system’s accounting routine is enabled; see 
acct (S). 


If the process ID, tty group ID, and process group ID of the calling process are equal, the SIGHUP signal 
is sent to each processes that has a process group ID equal to that of the calling process. 


See Also 


signal(S), wait(S) 


Warning 


See Warning in signal(S) 
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Name 


exp, log, pow, sqrt, log10 — Performs exponential, logarithm, power, square root functions. 


Syntax 


#include <math.h> 


double exp (x) 
double x; 


double log (x) 
double x; 


double pow (x, y) 
double x, y; 


double sqrt (x) 
double x; 


double log10 (x) 
double x; 


Description 


Exp returns the exponential function of x. 


Log returns the natural logarithm of x. 
Pow returns x’. 


Sqrt returns the square root of x. 


See Also 


intro(S), hypot(S), sinh(S) 


Diagnostics 


EXP (S) 


Exp and pow return a huge value when the correct value would overflow. A truly outrageous argument 
may also result in errno being set to ERANGE . Log returns a huge negative value and sets errno to 
EDOM when x is nonpositive. Pow returns a huge negative value and sets errno to EDOM when x is 
nonpositive and y is not an integer, or when x and y are both zero. Sgrt returns 0 and sets errno to 


EDOM when x is negative. 
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Name 


fclose, fflush — Closes or flushes a stream. 


Syntax 


#include <stdio.h> 


int fclose (stream) 
FILE «stream; 


int fflush (stream) 
FILE *stream; 


Description 


Fclose causes any buffers for the named stream to be emptied, and the file to be closed. Buffers allo- 
cated by the standard input/output system are freed. 


Fclose is performed automatically upon calling exit(S). 


Fflush causes any buffered data for the named output stream to be written to that file. The stream 
remains open. 


These functions return 0 for success, and EOF if any errors were detected. 


See Also 


close(S), fopen(S), setbuf(S) 
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Name 
c™ 


FCNTL (S) 


fentl — Controls open files. 


Syntax 


#include <fcntl.h> 


int fentl (fildes, cmd, arg) 
int fildes, cmd, arg; 


Description 


Fentl provides for control over open files. Fildes is an open file descriptor obtained from a creat, open, 
dup, fcntl, or pipe system call. 


The cmds available are: 


F_DUPFD 


F_GETFD 


F SETFD 


F GETFL 


F SETFL 


Returns a new file descriptor as follows: 

Lowest numbered available file descriptor greater than or equal to arg. 

Same open file (or pipe) as the original file. 

Same file pointer as the original file (i.e., both file descriptors share one file pointer). 
Same access mode (read, write or read/write). 

Same file status flags (i.e., both file descriptors share the same file status flags). 


The close-on-exec flag associated with the new file descriptor is set to remain open across 
exec(S) system calls. 


Gets the close-on-exec flag associated with the file descriptor fildes. If the low-order bit is 0 
the file will remain open across exec, otherwise the file will be closed upon execution of 
exec. 


Sets the close-on-exec flag associated with fildes to the low-order bit of arg (0 or 1 as 
above). 


Gets file status flags. 


Sets file status flags to arg. Only certain flags can be set. 


Fcntl fails if one or more of the following is true: 


Fildes is not a valid open file descriptor. [EBADF] 


Cmd is F DUPFD and 20 file descriptors are currently open. [EMFILE] 


Cmd is F DUPFD and arg is negative or greater than 20. [EINVAL] 


Return Value 


Cr) Upon successful completion, the value returned depends on cmd as follows: 
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F DUPFD 
F GETFD 
F SETFD 
F_GETFL 


F SETFL 


Otherwise, a value of —1 is returned and errno is set to indicate the error. 


See Also 


A new file descriptor 

Value of flag (only the low-order bit is defined) 
Value other than —1 

Value of file flags 


Value other than —1 


close(S), exec(S), open(S) 
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oo Name 


ferror, feof, clearerr, fileno — Determines stream status. 


Syntax 
#include <stdio.h> 


int feof (stream) 
FILE *stream; 


int ferror (stream) 
FILE *stream 


clearerr (Stream) 
FILE *stream 


int fileno(stream) 
FILE *stream; 
Description 
Feof returns nonzero when end-of-file is read on the named input stream, otherwise zero. 


Ferror returns nonzero when an error has occurred reading or writing the named stream, otherwise zero. 
Unless cleared by clearerr, the error indication lasts until the stream is closed. 


i Clearerr resets the error indication on the named stream. 
Fileno returns the integer file descriptor associated with the stream, see open(S). 


Feof, ferror, and fileno are implemented as macros; they cannot be redeclared. 


See Also 


open(S), fopen(S) 
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Name 


o 


floor, fabs, ceil, fmod — Performs absolute value, floor, ceiling and remainder functions. 


Syntax 
#include <math.h> 


double floor (x) 
double x; 


double ceil (x) 
double x; 


double fmod (x, y) 
double x, y; 


double fabs (x) 
double x; 
Description 
Fabs returns |x|. 
Floor returns the largest integer (as a double precision number) not greater than x. 
Ceil returns the smallest integer not less than x. 


Fmod returns the number f such that x = iy + f, for some integer i, and 0 < f<y. 


See Also 


abs(S) 
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Name 
_ 


fopen, freopen, fdopen — Opens a stream. 


Syntax 
#include <stdio.h> 


FILE *fopen (filename, type) 
char *filename, «type; 


FILE *freopen (filename, type, stream) 
char «filename, «type; 
FILE *stream; 


FILE *fdopen (fildes, type) 
int fildes; 
char *type; 

Description 


Fopen opens the file named by filename and associates a stream with it. Fopen returns a pointer to be 
used to identify the stream in subsequent operations. 


Type is a character string having one of the following values: 

r Open for reading 

w Create for writing 

a Append; open for writing at end of file, or create for writing 
r+ Open for update (reading and writing) 

w+ Create for update 

a+ Append; open or create for update at end of file 


Freopen substitutes the named file in place of the open stream. It returns the original value of stream. 
The original stream is closed, regardless of whether the open call ultimately succeeds. 


Freopen is typically used to attach the preopened constant names stdin, stdout, and stderr to specified 
files. 


Fdopen associates a stream with a file descriptor obtained from open, dup, creat, or pipe(S). The type 
of the stream must agree with the mode of the open file. The type must be provided because the stan- 
dard I/O library has no way to query the type of an open file descriptor. Fdopen returns the new 
stream. 


When a file is opened for update, both input and output may be done on the resulting stream. However, 
output may not be directly followed by input without an intervening fseek or rewind, and input may not 
be directly followed by output without an intervening fseek, rewind, or an input operation which en- 
counters the end of the file. 
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FOPEN (S) 
See Also 


open(S), fclose(S) 
Diagnostics 


Fopen and freopen return the pointer NULL if filename cannot be accessed. 
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Name 


fork — Creates a new process. 


Syntax 


int fork () 


Description 


Fork causes creation of a new process. The new process (child process) is an exact copy of the calling 
process (parent process) except for the following: 


The child process has a unique process ID. 
The child process has a different parent process ID (i.e., the process ID of the parent process). 


The child process has its own copy of the parent’s file descriptors. Each of the child’s file descriptors 
shares a common file pointer with the corresponding file descriptor of the parent. 


The child process’ utime, stime, cutime, and cstime are set to 0; see times(S). 
The time left on the parent’s alarm clock is not passed on to the child. 
Fork returns a value of 0 to the child process. 
Fork returns the process ID of the child process to the parent process. 
Fork will fail and no child process will be created if one or more of the following are true: 


The system-imposed limit on the total number of processes under execution would be exceeded. 
[EAGAIN] 


The system-imposed limit on the total number of processes under execution by a single user would 
be exceeded. [EAGAIN] 


Not enough memory is available to create the forked image. [ENOMEM] 


Return Value 


Upon successful completion, fork returns a value of 0 to the child process and returns the process ID of 
the child process to the parent process. Otherwise, a value of —1 is returned to the parent process, no 
child process is created, and errno is set to indicate the error. 


See Also 
exec(S), wait(S) 
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Name 


c 


fread, fwrite — Performs buffered binary input and output. 


Syntax 
#include <stdio.h> 


int fread ((char *) ptr, sizeof (*ptr), nitems, stream) 
FILE *stream; 


int fwrite ((char *) ptr, sizeof (*ptr), nitems, stream) 
FILE *stream; 
Description 


Fread reads, into a block beginning at ptr, nitems of data of the type of *ptr from the named input 
stream. It returns the number of items actually read. 


Fwrite appends at most nitems of data of the type of «ptr beginning at ptr to the named output stream. 
It returns the number of items actually written. 


See Also 


read(S), write(S), fopen(S), getc(S), putc(S), gets(S), puts(S), printf(S), scanf(S) 
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Name 


frexp, ldexp, modf — Splits floating-point number into a mantissa and an exponent. 


Syntax 


double frexp (value, eptr) 
double value; 
int *eptr; 


double Idexp (value, exp) 
double value; 


double modf (value, iptr) 
double value, «iptr; 
Description 


Frexp returns the mantissa of a double value as a double quantity, x, of magnitude less than 1, and 
stores an integer n such that value = x*2+**n indirectly through eptr. 


Ldexp returns the quantity value*(2**exp). 


Modf returns the positive fractional part of value and stores the integer part indirectly through iptr. 
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oo Name 


fseek, ftell, rewind — Repositions a stream. 


Syntax 
#include <stdio.h> 


int fseek (stream, offset, ptrname) 
FILE *stream; 

long offset; 

int ptrname; 


long ftell (stream) 
FILE *stream; 


rewind(stream) 
FILE *stream; 
Description 


Fseek sets the position of the next input or output operation on the stream. The new position is at the 
signed distance offset bytes from the beginning, the current position, or the end of the file, according as 
ptrname has the value 0, 1, or 2. 


Fseek undoes any effects of ungetc(S). 
After fseek or rewind, the next operation on an update file may be either input or output. 


Ftell returns the current value of the offset relative to the beginning of the file associated with the 
named stream. The offset is measured in bytes. 


Rewind(stream) is equivalent to fseek(stream, OL, 0). 


See Also 


lseek(S), fopen(S) 


Diagnostics 


Fseek returns nonzero for improper seeks, otherwise zero. 
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Name 


gamma — Performs log gamma function. 


Syntax 


#include <math.h> 
extern int signgam; 


double gamma (x) 
double x; 
Description 


Gamma returns /n|[(|x|)|. The sign of I'(|x|) is returned in the external integer signgam. The following 
C program fragment might be used to calculate I: 


y = gamma (x); 
if (y > 88.0) 
error (); 
y = exp (y) * signgam; 
Diagnostics 


For negative integer arguments, a huge value is returned, and errno is set to EDOM. 
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Name 


getc, getchar, fgetc, getw — Gets character or word from a stream. 


Syntax 
#include <stdio.h> 


int getc (stream) 
FILE «stream; 


int getchar () 


int fgetc (stream) 
FILE *stream; 


int getw (stream) 
FILE *stream; 
Description 
Getc returns the next character from the named input stream. 
Getchar() is identical to getc(stdin). 


Fgetc behaves like getc, but is a genuine function, not a macro; it may therefore be used as an argu- 
ment. Fgetc runs more slowly than getc, but takes less space per invocation. 


Getw returns the next word from the named input stream. It returns the constant EOF upon end-of-file 
or error, but since that is a valid integer value, feof and ferror(S) should be used to check the success of 
getw. Getw assumes no special alignment in the file. 


See Also 
ferror(S), fopen(S), fread(S), gets(S), putc(S), scanf(S) 


Diagnostics 


These functions return the integer constant EOF at the end-of-file or upon a read error. 
Notes 


Because getc is implemented as a macro, stream arguments with side effects are treated incorrectly. In 
particular, “getc( *f++ )” doesn’t work properly. 
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Name 


getcwd — Gets pathname of current working directory. 


Syntax 


len = getcwd (pnbuf, maxlen); 
int len; 

char *pnbuf; 

int maxlen; 


Description 


Getcwd determines the pathname of the current working directory and places it in pnbuf. The length ex- 
cluding the terminating NULL is returned. Maxlen is the length of pnbuf. If the length of the (null- 
terminated) pathname exceeds maxlen, it is treated as an error. 


Diagnostics 


A length <= 0 is returned on error. 


Notes 


maxlen (and pnbuf ) must be 1 more than the true maximum length of the pathname. 
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Name 


getenv — Gets value for environment name. 


Syntax 
char *getenv (name) 
char *name; 
Description 
Getenv searches the environment list (see environ(M)) for a string of the form name=value and returns 
value if such a string is present, otherwise 0 ( NULL ). 
See Also 


sh(C), exec(S) 
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Name 


getgrent, getgergid, getgrnam, setgrent, endgrent — Get group file entry. 


Syntax 
#include <grp.h> 
struct group *getgrent ( ); 


struct group *getgrgid (gid) 
int gid; 


struct group *getgrnam (name) 
char *name; 


int setgrent ( ); 


int endgrent ( ); 


Description 


Getgrent, getgrgid and getgrnam each return pointers. The format of the structure is defined in 
/usr /include/grp.h. 


The members of this structure are: 
gr name The name of the group. 
gr passwd The encrypted password of the group. 
gr gid The numerical group ID. 
gr mem Null-terminated vector of pointers to the individual member names. 


Getgrent reads the next line of the file, so successive calls may be used to search the entire file. Get- 
grgid and getgrnam search from the beginning of the file until a matching gid or name is found, or 
end-of-file is encountered. 


A call to setgrent has the effect of rewinding the group file to allow repeated searches. Endgrent may 
be called to close the group file when processing is complete. 


Files 


/etc/group 


See Also 


getlogin(S), getpwent(S), group(M) 


Diagnostics 


A null pointer (0) is returned on end-of-file or error. 
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Notes 


All information is contained in a static area, so it must be copied if it is to be saved. 
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Name 


getlogin — Gets login name. 


Syntax 


char *getlogin ( ); 


Description 


Getlogin returns a pointer to the login name as found in /etc/utmp. It may be used in conjunction with 
getpwnam to locate the correct password file entry when the same user ID is shared by several login 
names. 


If getlogin is called within a process that is not attached to a terminal device, it returns NULL. The 
correct procedure for determining the login name is to call cuserid, or to call getlogin and if it fails, to 
call getpwuid. 


Files 


/etc/utmp 


See Also 


cuserid(S), getgrent(S), getpwent(S), utmp(M) 


Diagnostics 


Returns NULL if name not found. 


Notes 


The return values point to static data whose content is overwritten by each call. 
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o™ Name 


getopt — Gets option letter from argument vector. 


Syntax 


#include <stdio.h> 


int getopt (argc, argv, optstring) 
int argc; 

char **argy; 

char *optstring; 

extern char *optarg; 

extern int optind; 


Description 


Getopt returns the next option letter in argv that matches a letter in optstring. Optstring is a string of 
recognized option letters; if a letter is followed by a colon, the option is expected to have an argument 
that may or may not be separated from it by whitespace. Optarg is set to point to the start of the op- 
tion argument on return from getopt. 


Getopt places in optind the argv index of the next argument to be processed. Because optind is 
external, it is normally initialized to zero automatically before the first call to getopt. 


When all options have been processed (i.e., up to the first nonoption argument), getopt returns EOF. 
ff’ The special option -- may be used to delimit the end of the options; EOF will be returned, and -- will be 
skipped. 


Diagnostics 


Getopt prints an error message on stderr and returns a question mark (?) when it encounters an option 
letter not included in optstring. 


Examples 


The following code fragment shows how one might process the arguments for a command that can take 
the mutually exclusive options a and b, and the options f and o, both of which require arguments: 


main (argc, argv) 

int argc; 

char **argv; 

{ 
int Cc: 
extern int optind; 
extern char *optarg; 


while ((c = getopt (argc, argv, "abf:o:")) != EOF) 
switch (c) { 
case ‘a: 


o™ if (bflg) 


else 


errflg++; 
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aflg++; 
break; 
case 'b’: 
if (aflg) 
errflg++; 
else 
bproc(); 
break; 
case 'f’: 
ifile = optarg; 
break; 
case ‘0’: 
ofile = optarg; 
bufsiza = 512; 
break; 
case ‘2’: 
errflg++; 
if (errflg) { 
fprintf (stderr, "usage: . . . "); 
exit (S); 


for( ; optind < argc; optind++) { 
if (access (argv[optind], 4)) { 
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Name 


getpass — Reads a password. 


Syntax 
char *getpass (prompt) 
char *prompt; 
Description 


Getpass reads a password from the file /dev/tty, or if that cannot be opened, from the standard input, 
after prompting with the null-terminated string prompt and disabling echoing. A pointer is returned to 
a null-terminated string of at most eight characters. 


Files 


/dev/tty 


See Also 


crypt(S) 


Notes 


The return value points to static data whose content is overwritten by each call. 
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Name 


getpid, getpgrp, getppid — Gets process, process group, and parent process IDs. 


Syntax 
int getpid () 
int getpgrp () 


int getppid () 


Description 
Getpid returns the process ID of the calling process. 
Getpgrp returns the process group ID of the calling process. 


Getppid returns the parent process ID of the calling process. 


See Also 
exec(S), fork(S), intro(S), setpgrp(S), signal(S) 
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Name 


getpw — Gets password for a given user ID. 


Syntax 
getpw (uid, buf) 
int uid; 
char *buf; 
Description 
Getpw searches the password file for the uid, and fills in buf with the corresponding line; it returns 
nonzero if uid could not be found. The line is null-terminated. Uid must be an integer value. 


Files 


/etc/passwd 


See Also 


getpwent(S), passwd(M) 


Diagnostics 


Returns nonzero on error. 


Notes 


This routine is included only for compatibility with prior systems and should not be used; see 
getpwent(S) for routines to use instead. 
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Name 
f+ 
getpwent, getpwuid, getpwnam, setpwent, endpwent — Gets password file entry. 
Syntax 
#include <pwd.h> 
struct passwd *getpwent ( ); 
struct passwd *getpwuid (uid) 
int uid; 
struct passwd *getpwnam (name) 
char *name; 
int setpwent ( ); 
int endpwent ( ); 
Description 
Getpwent, getpwuid and getpwnam each returns a pointer to a structure containing the fields of an entry 
line in the password file. The structure of a password entry is defined in /usr/include/pwd.h. 
The fields have meanings described in passwd(M). (The pw_comment field is unused.) 
a Getpwent reads the next line in the file, so successive calls can be used to search the entire file. 


Getpwuid and getpwnam search from the beginning of the file until a matching uid or name is found, or 
EOF is encountered. 


A call to setpwent has the effect of rewinding the password file to allow repeated searches. Endpwent 
may be called to close the password file when processing is complete. 


Files 


/etc/passwd 


See Also 


getlogin(S), getgrent(S), passwd(M) 


Diagnostics 


Null pointer (0) returned on EOF or error. 


Notes 


All information is contained in a static area so it must be copied if it is to be saved. 
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Name 


gets, fgets — Gets a string from a stream. 


Syntax 
#include <stdio.h> 


char «gets (s) 
char *s; 


char *fgets (s, n, stream) 
char *s; 

int n; 

FILE *stream; 


Description 


Gets reads a string into s from the standard input stream stdin. The function replaces the newline 
character at the end of the string with a null character before copying to s. Gets returns a pointer to s. 


Fgets reads characters from the stream until a newline character is encountered or until n—1 characters 
have been read. The characters are then copied to the string s. A null character is automatically ap- 
pended to the end of the string before copying. Fgets returns a pointer to s. 


See Also 
ferror(S), fopen(S), fread(S), getc(S), puts(S), scanf(S) 


Diagnostics 


Gets and fgets return the constant pointer NULL upon end-of-file or error. 


Notes 


Gets deletes the newline ending its input, but fgets keeps it. 
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Name 


getuid, geteuid, getgid, getegid — Gets real user, effective user, real group, and effective group IDs. 


Syntax 
int getuid () 
int geteuid () 
int getgid () 


int getegid () 


Description 
Getuid returns the real user ID of the calling process. 
Geteuid returns the effective user ID of the calling process. 
Getgid returns the real group ID of the calling process. 


Getegid returns the effective group ID of the calling process. 


See Also 


intro(S), setuid(S) 
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Name 


hypot, cabs — Determines Euclidean distance. 


Syntax 
#include <math.h> 


double hypot (x, y) 
double x, y; 


double cabs (z) 

struct {double x, y;} z; 
Description 

Hypot and cabs return 


sqrt(x*x + y*y) 


Both take precautions against unwarranted overflows. 


See Also 


sqrt in exp(S) 
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Name 


ioctl — Controls character devices. 


Syntax 
#include <sys/ioctl.h> 
ioctl(fildes, request, arg) 
int fildes; 

Description 


Ioctl performs a variety of functions on character special files (devices). The writeups of various devices 
in Section M discuss how ioctl applies to them. 


Toctl will fail if one or more of the following are true: 
Fildes is not a valid open file descriptor. [EBADF] 
Fildes is not associated with a character special device. [ENOTTY] 


Request or arg is not valid. See tty(M). [EINVAL] 


Return Value 


If an error has occurred, a value of —1 is returned and errno is set to indicate the error. 


See Also 


tty(M) 
Notes 


When using ioct] with the include file <termio.h> be certain to include the file <sys/types.h> 
BEFORE including <termio.h> . 
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Name 


kill — Sends a signal to a process or a group of processes. 


Syntax 
int kill (pid, sig) 
int pid, sig; 
Description 


Kill sends a signal to a process or a group of processes. The process or group of processes to which the 
signal is to be sent is specified by pid. The signal that is to be sent is specified by sig and is either one 
from the list given in signal(S), or 0. If sig is 0 (the null signal), error checking is performed but no 
signal is actually sent. This can be used to check the validity of pid. 


The effective user ID of the sending process must match the effective user ID of the receiving process 
unless, the effective user ID of the sending process is super-user, or the process is sending to itself. 


The processes with a process ID of 0 and a process ID of 1 are special processes (see intro(S)) and will 
be referred to below as procO and proc! respectively. 


If pid is greater than zero, sig will be sent to the process whose process ID is equal to pid. Pid may 
equal 1. 


If pid is 0, sig will be sent to all processes excluding procO and procl whose process group ID is equal to 
the process group ID of the sender. 


If pid is —1 and the effective user ID of the sender is not super-user, sig will*be sent to all processes ex- 
cluding proc0 and proc! whose real user ID is equal to the effective user ID of the sender. 


If pid is —1 and the effective user ID of the sender is super-user, sig will be sent to all processes exclu- 
ding proc0 and procl. 


If pid is negative but not —1, sig will be sent to all processes whose process group ID is equal to the ab- 
solute value of pid. 


Kill will fail and no signal will be sent if one or more of the following are true: 
Sig is not a valid signal number. [EINVAL] 
No process can be found corresponding to that specified by pid. [ESRCH] 
The sending process is not sending to itself, its effective user ID is not super-user, and its effective 
user ID does not match the real user ID of the receiving process. [EPERM] 
Return Value 
Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 
See Also 


Cy kill(C), getpid(S), setpgrp(S), signal(S) 
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Name 


I3tol, Itol3 — Converts between 3-byte integers and long integers. 


Syntax 


I3tol (Ip, cp, n) 
long «lp; 

char *cp; 

int n; 


Itol3 (cp, Ip, n) 
char *cp; 

long *lp; 

int n; 


Description 


L3tol converts a list of n 3-byte integers packed into a character string pointed to by cp into a list of 
long integers pointed to by /p. 


Ltol3 performs the reverse conversion from long integers (/p) to 3-byte integers (cp). 


These functions are useful for file system maintenance where the block numbers are 3 bytes long. 


See Also 


filesystem(F) 
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Name 


link — Links a new filename to an existing file. 


Syntax 
int link (path1, path2) 
char *path1, *path2; 
Description 


Path! points to a pathname naming an existing file. Path2 points to a pathname giving the new 
filename to be linked. Link makes a new link by creating a new directory entry for the existing file 
using the new name. The contents of the existing file can then be accessed using either name. 


Link will fail and no link will be created if one or more of the following are true: 
A component of either path prefix is not a directory. [ENOTDIR] 
A component of either path prefix does not exist. [ENOENT] 
A component of either path prefix denies search permission. [EACCES] 
The file named by path! does not exist. [ENOENT] 
The link named by path2 already exists. [EEXIST] 
The file named by path! is a directory and the effective user ID is not super-user. [EPERM] 


The link named by path2 and the file named by path/ are on different logical devices (file systems). 
[EXDEV] 


Path2 points to a null pathname. [ENOENT] 


The requested link requires writing in a directory with a mode that denies write permission. 
[EACCES] 


The requested link requires writing in a directory on a read-only file system. [EROFS] 


Path points outside the process’ allocated address space. [EFAULT] 


Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


In(C) 
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Name 


lock — Locks a process in primary memory. 


Syntax 


lock(flag) 


Description 


If the flag argument is nonzero, the process executing this call will not be swapped except if it is re- 
quired to grow. If the argument is zero, the process is unlocked. This call may only be executed by the 
super-user. 


Notes 


Locked processes interfere with the compaction of primary memory and can cause deadlock. Systems 
with small memory configurations should avoid using this call. It is best to lock process soon after 
booting because that will tend to lock them into one end of memory. 


This feature is a XENIX specific enhancement and may not be present in all UNIX implementations. 
This routine may be linked using the linker option - Ix. 
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Name 


lockf — Provide semaphores and record locking on files. 


Syntax 


#include <unlstd.h> 
lockf(fildes, function, size) 
long size; 

int fildes, function; 


Description 


Lockf locks a specified region of the file given by the file descriptor, filedes , against access by all other 
processes. Other processes which attempt to use the locked region will either return an error, or wait 
until the region is unlocked. More than one region in a file can be locked. When the process closes the 
file (or terminates) all locks are removed. 


The function argument specifies what action to take. The possible values are: 


F ULOCK 
Unlock a locked region. 


F LOCK 
Lock the region for exclusive use. If the region is not available, the calling process sleeps until the 
region is available. 


F TLOCK 
Test for locks, then lock the region for exclusive use. If the region is not available, /ockf returns 
immediately and sets errno to EACCESS . 


F TEST 
Test the region for other process locks. This argument is used to determine whether or not another 
process has placed a lock on the specified region. 


The size argument is the number of contiguous bytes to be locked or unlocked. The region to be locked 
starts at the current position in the file and extends forward for a positive size and backward for a nega- 
tive size. If the size is 0, the region extends from the current position in the file to the current or future 
end of the file. 


A process can create overlapping regions if desired. It cannot overlap regions locked by other processes. 
Adjacent regions locked by the same process are always combined into a single region. 


A process can unlock all or part of any locked region. When regions are not fully unlocked, the remai- 
ning regions are still locked by the process. If the center of a locked region is unlocked, /ockf creates two 
new locked regions from the remaining portions of the original region. 


Return Values 


Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. If a lock request is made and the table of active locks is full, errno is set to 
EDEADLOCK . If an attempt is made to unlock the center section of a locked region when no active 
lock table entries are available, errno is set to EDEADLOCK . If fildes is not a valid open file descriptor, 
errno is set to EBADF . 
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See Also 


open(S), creat(S), read(S), write(S), close(S). 


Notes 


This routine may be linked with the linker option - Ix. 
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Name 


locking — Locks or unlocks a file region for reading or writing. 


Syntax 


locking(fildes, mode, size); 
int fildes, mode; 
long size; 


Description 


Locking allows a specified number of bytes in a file to be controlled by the locking process. Other pro- 
cesses which attempt to read or write a portion of the file containing the locked region may sleep until 
the area becomes unlocked depending upon the mode in which the file region was locked. 


A process that attempts to write to or read a file region that has been locked against reading and writing 
by another process (using the LK LOCK or LK_NBLCK mode) will sleep until the region of the file has 
been released by the locking process. 


A process that attempts to write to a file region that has been locked against writing by another process 
(using the LK RLCK or LK NBRLCK mode) will sleep until the region of the file has been released by 
the locking process, but a read request for that file region will proceed normally. 


A process that attempts to lock a region of a file that contains areas that have been locked by other pro- 
cesses will sleep if it has specified the LK LOCK or LK _RLCK mode in its lock request, but will return with 
the error EACCES if it specified LK NBLCK or LK_NBRLCK. 


Fildes is the value returned from a successful creat, open, dup, or pipe system call. 


Mode specifies the type of lock operation to be performed on the file region. The available values for 
mode are: 


LK UNLCK 0 
Unlocks the specified region. The calling process releases a region of the file it had previously 
locked. 


LK LOCK 1 
Locks the specified region. The calling process will sleep until the entire region is available if any 
part of it has been locked by a different process. The region is then locked for the calling process 
and no other process may read or write in any part of the locked region. (lock against read and 
write). 


LK NBLCK 2 
Locks the specified region. If any part of the region is already locked by a different process, return 
the error EACCES instead of waiting for the region to become available for locking (nonblocking 
lockrequest). 


LK RLCK 3 
Same as LK LOCK except that the locked region may be read by other processes (read permitted 


lock). 
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See 


LK NBRLCK 4 
Same as LK NBLCK except that the locked region may be read by other processes (nonblocking, 
read permitted lock). 


The Jocking utility uses the current file pointer position as the starting point for the /ocking of the file 
segment. So a typical sequence of commands to /ock a specific range within a file might be as follows: 


fd=open("datafile",O RDWR); 
Iseek(fd, 200L, 0); 
locking(fd, LK_ LOCK, 200L); 


Accordingly, to Jock or unlock an entire file a seek to the beginning of the file (position 0) must be done 
and then a Jocking call must be executed with a size of 0. 


Size is the number of contiguous bytes to be locked or unlocked. The region to be locked starts at the 
current offset in the file. If size is 0, the entire file (up to a maximum of 2 to the power of 30 bytes) is 
locked or unlocked. Size may extend beyond the end of the file, in which case only the process issuing 
the lock call may access or add information to the file within the boundary defined by size. 


The potential for a deadlock occurs when a process controlling a locked area is put to sleep by accessing 
another process’ locked area. Thus calls to locking, read, or write scan for a deadlock prior to sleeping 
on a locked region. An error return is made if sleeping on the locked region would cause a deadlock. 


Lock requests may, in whole or part, contain or be contained by a previously locked region for the same 
process. When this occurs, or when adjacent regions are locked, the regions are combined into a single 
area if the mode of the lock is the same (i.e.; either read permitted or regular lock). If the mode of the 
overlapping locks differ, the locked areas will be assigned assuming that the most recent request must be 
satisfied. Thus if a read only lock is applied to a region, or part of a region, that had been previously 
locked by the same process against both reading and writing, the area of the file specified by the new 
lock will be locked for read only, while the remaining region, if any, will remain locked against reading 
and writing. There is no arbitrary limit to the number of regions which may be locked in a file. There 
is however a system-wide limit on the total number of locked regions. This limit is 200 for XENIX sys- 
tems. 


Unlock requests may, in whole or part, release one or more locked regions controlled by the process. 
When regions are not fully released, the remaining areas are still locked -by the process. Release of the 
center section of a locked area requires an additional locked element to hold the separated section. If 
the lock table is full, an error is returned, and the requested region is not released. Only the process 
which locked the file region may unlock it. An unlock request for a region that the process does not 
have locked, or that is already unlocked, has no effect. When a process terminates, all locked regions 
controlled by that process are unlocked. 


If a process has done more than one open on a file, a// locks put on the file by that process will be 
released on the first close of the file. 


Although no error is returned if locks are applied to special files or pipes, read/write operations on these 
types of files will ignore the locks. Locks may not be applied to a directory. 


Also 


creat(S), open(S), read(S), write(S), dup(S), close(S), lseek(S) 


Diagnostics 


Locking returns the value (int) -1 if an error occurs. If any portion of the region has been locked by 
another process for the LK_LOCK and LK_RLCK actions and the lock request is to test only, errno is set 
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to EACCES. If the file specified is a directory, errno is set to EACCES. If locking the region would 
cause a deadlock, errno is set to EDEADLOCK. If there are no more free internal locks, errno is set to 
EDEADLOCK. 


Notes 


This routine may be linked with the linker option - Ix. 
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Name 


c 


lsearch — Performs linear search and update. 


Syntax 


char *lsearch (key, base, nelp, width, compar) 
char «key; 

char «base; 

int *nelp; 

int width; 

int (*compar)(); 


Description 


Lsearch is a linear search routine generalized from Knuth (6.1) Algorithm Q. It returns a pointer into a 
table indicating the location at which a datum may be found. If the item does not occur, it is added at 
the end of the table. The first argument is a pointer to the datum to be located in the table. The se- 
cond argument is a pointer to the base of the table. The third argument is the address of an integer 
containing the number of items in the table. It is incremented if the item is added to the table. The 
fourth argument is the width of an element in bytes. The last argument is the name of the comparison 
routine. It is called with two arguments which are pointers to the elements being compared. The 
routine must return zero if the items are equal, and nonzero otherwise. 


Notes 


de Unpredictable events can occur if there is not enough room in the table to add a new item. 


See Also 


bsearch(S), qsort(S) 
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Name 


Iseek — Moves read/write file pointer. 


Syntax 


long Iseek (fildes, offset, whence) 
int fildes; 

long offset; 

int whence; 


Description 


Fildes is a file descriptor returned from a creat, open, dup, or fcntl system call. Lseek sets the file 
pointer associated with fildes as follows: 


If whence is 0, the pointer is set to offset bytes. 
If whence is 1, the pointer is set to its current location plus offset. 
If whence is 2, the pointer is set to the size of the file plus offset. 


Upon successful completion, the resulting pointer location as measured in bytes from the beginning of 
the file is returned. 


Lseek will fail and the file pointer will remain unchanged if one or more of the following are true: 
Fildes is not an open file descriptor. [EBADF] 
Fildes is associated with a pipe or fifo. [ESPIPE] 
Whence is not 0, 1 or 2. [EINVAL and SIGSYS signal] 
The resulting file pointer would be negative. [EINVAL] 
Some devices are incapable of seeking. The value of the file pointer associated with such a device is 
undefined. 
Return Value 
Upon successful completion, a nonnegative integer indicating the file pointer value is returned. Oth- 
erwise, a value of —1 is returned and errno is set to indicate the error. 
See Also 


creat(S), dup(S), fentl(S), open(S) 
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Name 


c~ 


malloc, free, realloc, calloc — Allocates main memory. 


Syntax 
char «malloc (size) unsigned size; 


free (ptr) 
char *ptr; 


char *realloc (ptr, size) 
char *ptr; 

unsigned size; 

char *calloc (nelem, elsize) 
unsigned nelem, elsize; 


Description 


Malloc and free provide a simple general-purpose memory allocation package. Malloc returns a pointer 
to a block of at least size bytes beginning on a word boundary. 


The argument to free is a pointer to a block previously allocated by malloc; this space is made available 
for further allocation, but its contents are left undisturbed. 


Needless to say, grave disorder will result if the space assigned by malloc is overrun or if some random 
ie number is handed to free. 


Malloc allocates the first contiguous reach of free space found in a circular search from the last block 
allocated or freed, coalescing adjacent free blocks as it searches. It calls sbrk (see sbrk(S)) to get more 
memory from the system when there is no suitable space already free. 


Realloc changes the size of the block pointed to by ptr to size bytes and returns a pointer to the (pos- 
sibly moved) block. The contents will be unchanged up to the lesser of the new and old sizes. 


Realloc also works if ptr points to a block freed since the last call of malloc, realloc, or calloc; thus se- 
quences of free, malloc and realloc can exploit the search strategy of malloc to do storage compaction. 


Calloc allocates space for an array of nelem elements of size elsize. The space is initialized to zeros. 
Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coer- 
cion) for storage of any type of object. 

Diagnostics 


Malloc, realloc and calloc return a null pointer (0) if there is no available memory or if the area has 
been detectably corrupted by storing outside the bounds of a block. When realloc returns 0, the block 
pointed to by ptr may be destroyed. 
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Name 


mknod — Makes a directory, or a special or ordinary file. 


Syntax 


int mknod (path, mode, dey) 
char *path; 
int mode, dey; 


Description 


Mknod creates a new file named by the pathname pointed to by path. The mode of the new file is ini- 
tialized from mode. Where the value of mode is interpreted as follows: 


0170000 File type; one of the following: 
0010000 Named pipe special 
0020000 Character special 
0040000 Directory 
0050000 Name special file 
0060000 Block special 
0100000 or 0000000 Ordinary file 


0004000 Set user ID on execution 
0002000 Set group ID on execution 
0001000 Save text image after execution 


0000777 Access permissions; constructed from the following 
0000400 Read by owner 
0000200 Write by owner 
0000100 Execute (search on directory) by owner 
0000070 Read, write, execute (search) by group 
0000007 Read, write, execute (search) by others 


Values of mode other than those above are undefined and should not be used. 


The file’s owner ID is set to the process’ effective user ID. The file’s group ID is set to the process’ ef- 
fective group ID. 


The low-order 9 bits of mode are modified by the process’ file mode creation mask: all bits set in the 
process’ file mode creation mask are cleared. See uwmask(S). If mode indicates a block, character, or 
name special file, then dev is a configuration dependent specification of a character or block I/O device. 
If mode does not indicate a block, character, or name special file, then dev is ignored. For block and 
character special files, dev is the special file’s device number. For name special files, dev is the type of 
the name file, either a shared memory file or a semaphore. 


Mknod may be invoked only by the super-user for file types other than named pipe special. 
Mknod will fail and the new file will not be created if one or more of the following are true: 


The process’ effective user ID is not super-user, and the file type is not named pipe special. 
[EPERM] 
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A component of the path prefix is not a directory. [ENOTDIR] 

A component of the path prefix does not exist. [ENOENT] 

The directory in which the file is to be created is located on a read-only file system. [EROFS] 
The named file exists. [EEXIST] 


Path points outside the process’ allocated address space. [EFAULT] 


Return Value 
Upon successful completion a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 

See Also 


mkdir(C), mknod(C), chmod(S), creatsem(S), exec(S), sdget(S), umask(S), filesystem(F) 


Notes 
Semaphore files should be created with the creatsem(S) system call. 


Share data files should be created with the sdget(S) system call. 
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Name 


mktemp — Makes a unique filename. 


Syntax 
char *mktemp(template) 
char *template; 
Description 


Mktemp replaces template with a unique filename, and returns a pointer to the name. The template 
should look like a filename with six trailing X’s, which will be replaced with the current process ID pre- 
ceded by a character which makes the name unique. 


See Also 


getpid(S) 
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Name 


monitor — Prepares execution profile. 


Syntax 
monitor (lowpc, highpc, buffer, bufsize, nfunc) 
int (*lowpc\ ), (*highpcy ); 
short buffer| |; 
int bufsize, nfunc; 


Description 


Monitor is an interface to profil(S). Lowpc and highpc are the addresses of two functions; buffer is the 
address of a user-supplied array of bufsize short integers. Monitor arranges to record a histogram of 
periodically sampled values of the program counter, and of counts of calls of certain functions, in the 
buffer. The lowest address sampled is that of Jowpc and the highest is just below highpc. At most 
nfunc call counts can be kept; only calls of functions compiled with the profiling option —p of cc(CP) 
are recorded. For the results to be significant, especially where there are small, heavily used routines, it 
is suggested that the buffer be no more than a few times smaller than the range of locations sampled. 


To profile the entire program, it is sufficient to use 
extern etext(); 
avanitor(Gnt (*)())2, etext, buf, bufsize, nfunc); 

Etext lies just above all the program text. 

To stop execution monitoring and write the results on the file mon.out, use 
monitor((int (*)())0); 


prof(CP) can then be used to examine the results. 


Files 


mon.out 


See Also 
cc(CP), prof(CP), profil(S) 
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Name 


mount — Mounts a file system. 


Syntax 
int mount (spec, dir, rwflag) 
char *spec, *dir; 
int rwflag; 


Description 


Mount requests that a removable file system contained on the block special file identified by spec be 
mounted on the directory identified by dir. Spec and dir are pointers to pathnames. 


Upon successful completion, references to the file dir will refer to the root directory on the mounted file 
system. 


The low-order bit of rwflag is used to control write permission on the mounted file system; if 1, writing 
is forbidden, otherwise writing is permitted according to individual file accessibility. 


Mount may be invoked only by the super-user. 
Mount will fail if one or more of the following are true: 
The effective user ID is not super-user. [EPERM] 
Any of the named files does not exist. [ENOENT] 
A component of a path prefix is not a directory. [ENOTDIR] 
Spec is not a block special device. [ENOTBLK] 
The device associated with spec does not exist. [ENXIO] 
Dir is not a directory. [ENOTDIR] 
Spec or dir points outside the process’ allocated address space. [EFAULT] 
Dir is currently mounted on, is someone’s current working directory or is otherwise busy. [EBUSY] 


The device associated with spec is currently mounted. [EBUSY] 


~ Return Value 


Upon successful completion a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


mount(C), umount(S) 
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Name 


nap — Suspends execution for a short interval. 


Syntax 
long nap(period) 
long period; 

Description 
The current process is suspended from execution for at least the number of milliseconds specified by 
period, or until a signal is received. 

Return Value 
On successful completion, a long integer indicating the number of milliseconds actually slept is returned. 
If the process recieved a signal while napping, the return value will be -1, and errno will be set to 
EINTR. 

Notes 
This function is driven by the system clock, which in most cases has a granularity of tens of mil- 
liseconds. This function may be linked with the linker option - Ix. 


See Also 


sleep(S) 
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Name 


nice — Changes priority of a process. 


Syntax 
int nice (incr) 
int incr; 
Description 


Nice adds the value of incr to the nice value of the calling process. A process’ nice value is a positive 
number for which a higher value results in lower CPU priority. 


A maximum nice value of 39 and a minimum nice value of 0 are imposed by the system. Requests for 
values above or below these limits result in the nice value being set to the corresponding limit. 


Nice will not change the nice value if incr is negative and the effective user ID of the calling process is 
not super-user. [EPERM] 
Return Value 


Upon successful completion, nice returns the new nice value minus 20. Note that nice is unusual in the 
way return codes are handled. It differs from most other system calls in two ways: the value —1 is a 
valid return code (in the case where the new nice value is 19), and the system call either works or ig- 
nores the request; there is never an error. 


See Also 


nice(C), exec(S) 
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Name 


nlist — Gets entries from name list. 


Syntax 


#include <a.out.h> 
nlist (filename, nl) 
char *filename; 
struct nlist ni[ |; 


Description 


Nlist examines the name list in the given executable output file and selectively extracts a list of values. 
The name list consists of an array of structures containing names, types and values. The list is ter- 
minated with a null name. Each name is looked up in the name list of the file. If the name is found, 
the type and value of the name are inserted in the next two fields. If the name is not found, both entries 
are set to 0. See a.out(F) for a discussion of the symbol table structure. 


See Also 


a.out(F), xlist(S) 


Diagnostics 


Nlist return —1 and sets all type entries to 0 if the file cannot be read, is not an object file, or contains 
an invalid name list. Otherwise, n/ist returns 0. A return value of 0 does not indicate that any or all 
symbols were found. 
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Name 


OPEN (S) 


open — Opens file for reading or writing. 


Syntax 


#include <fcntl.h> 
int open (path, oflag|, mode}) 


char *path; 


int oflag, mode; 


Description 


Path points to a pathname naming a file. Open opens a file descriptor for the named file and sets the 
file status flags according to the value of oflag. Oflag values are constructed by or-ing flags from the 
following list (only one of the first three flags below may be used): 


O RDONLY Open for reading only. 


O_WRONLY Open for writing only. 


O RDWR 


O NDELAY 


O APPEND 


O CREAT 
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Open for reading and writing. 

This flag may affect subsequent reads and writes. See read(S) and write(S). 
When opening a FIFO with O RDONLY or O_WRONLY set: 

If O NDELAY is set: 


An open for reading-only will return without delay. An open for writing-only will re- 
turn an error if no process currently has the file open for reading. 


If O NDELAY is clear: 


An open for reading-only will block until a process opens the file for writing. An 
open for writing-only will block until a process opens the file for reading. 


When opening a file associated with a communication line: 
If O NDELAY is set: 
The open will return without waiting for carrier. 
If O NDELAY is clear: 
The open will block until carrier is present. 
If set, the file pointer will be set to the end of the file prior to each write. 


If the file exists, this flag has no effect. Otherwise, the file’s owner ID is set to the 
process’ effective user ID, the file’s group ID is set to the process’ effective group ID, and 
the low-order 12 bits of the file mode are set to the value of mode modified as follows 
(see creat(S)): 


All bits set in the process’ file mode creation mask are cleared. See umask(S). 
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The “‘save text image after execution bit” of the mode is cleared. See chmod(S). 
O TRUNC If the file exists, its length is truncated to 0 and the mode and owner are unchanged. 
O EXCL If O EXCL and O CREAT are set, open will fail if the file exists. 


OSYNCW _ Every write to this file descriptor will be synchronous, that is, when the write system call 
completes data is guaranteed to have been written to disk. 


Upon successful completion a nonnegative integer, the file descriptor, is returned. 
The file pointer used to mark the current position within the file is set to the beginning of the file. 
The new file descriptor is set to remain open across exec system calls. See fcntl(S). 
No process may have more than 20 file descriptors open simultaneously. 
The named file is opened unless one or more of the following are true: 
A component of the path prefix is not a directory. [ENOTDIR] 
O CREAT is not set and the named file does not exist. [ENOENT] 
A component of the path prefix denies search permission. [EACCES] 
Oflag permission is denied for the named file. [EACCES] 
The named file is a directory and offlag is write or read/write. [EISDIR] 
The named file resides on a read-only file system and offag is write or read/write. [EROFS] 
Twenty file descriptors are currently open. [EMFILE] 


The named file is a character special or block special file, and the device associated with this special 
file does not exist. [ENXIO] 


The file is a pure procedure (shared text) file that is being executed and oflag is write or read/write. 
[ETXTBSY] 


Path points outside the process’ allocated address space. [EFAULT] 
O CREAT and O EXCL are set, and the named file exists. [EEXIST] 
O NDELAY is set, the named file is a FIFO, O WRONLY is set, and no process has the file open for 
reading. [ENXIO] 
Return Value 
Upon successful completion, a nonnegative integer, namely a file descriptor, is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 
See Also 


close(S), creat(S), dup(S), fentl(S), lseek(S), read(S), write(S) 
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Notes 


The O_ SYNCW flag is a XENIX specific enhancement which may not be present in all UNIX implemen- 
tations. 
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Name 


opensem — Opens a semaphore. 


Syntax 


sem num = opensem(sem_ name); 
int sem num; 
char *sem_ name; 


Description 


Opensem opens a semaphore named by sem_name and returns the unique semaphore identification 
number sem_num used by waitsem and sigsem. Creatsem should always be called to initialize the sema- 
phore before the first attempt to open it. 


See Also 


creatsem(S), waitsem(S), sigsem(S) 


Diagnostics 


Opensem returns the value —1 if an error occurs. If the semaphore named does not exist, errno is set to 
ENOENT. If the file specified is not a semaphore file (i.e., a file previously created by a process using a 
call to creatsem), errno is set to ENOTNAM. If the semaphore has become invalid due to inappropriate 
use, errno is set to ENAVAIL. 


Warning 


It is not advisable to open the same semaphore more than once. Though it is possible to do this it may 
result in a serious deadlock. 


Notes 


This feature is a XENIX specific enhancement which may not be present in all UNIX implementations. 
This function may be linked with the linker option - Ix. 
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Name 


pause — Suspends a process until a signal occurs. 


Syntax 


int pause (); 


Description 


Pause suspends the calling process until it receives a signal. The signal must be one that is not 
currently set to be ignored by the calling process. 


If the signal causes termination of the calling process, pause will not return. 
If the signal is caught by the calling process and control is returned from the signal catching function 


(see signal(S)), the calling process resumes execution from the point of suspension; with a return value 
of —1 from pause and errno set to EINTR. 


See Also 


alarm(S), kill(S), signal(S), wait(S) 
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Name 


c~ 


perror, sys errlist, sys _nerr, errno — Sends system error messages. 


Syntax 


perror (S) 
char *s; 


int syS_nerr; 
char «sys errlist| |; 


int errno; 


Description 


Perror produces a short error message on the standard error, describing the last error encountered du- 
ring a system call from a C program. First the argument string s is printed, then a colon, then the mes- 
sage and a newline. To be of most use, the argument string should be the name of the program that in- 
curred the error. The error number is taken from the external variable errno, which is set when errors 
occur but not cleared when correct calls are made. 


To simplify variant formatting of messages, the vector of message strings sys_errlist is provided; errno 
can be used as an index in this table to get the message string without the newline. Sys_nerr is the 
number of entries provided for in the table; it should be checked because new error codes may be added 
to the system before they are added to the table. 


cy 


See Also 


intro(S) 
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Name 


pipe — Creates an interprocess pipe. 


Syntax 
int pipe (fildes) 
int fildes[2]; 
Description 


Pipe creates an I/O mechanism called a pipe and returns two file descriptors in the array fildes. 
Fildes[0] is opened for reading and fildes[1] is opened for writing. The descriptors remain open across 
fork(S) system calls, making communication between parent and child possible. 


Writes up to 5120 bytes of data are buffered by the pipe before the writing process is blocked. A read 
on file descriptor fildes[0] accesses the data written to fildes[1] on a first-in-first-out basis. 


No process may have more than 20 file descriptors open simultaneously. 


Pipe will fail if 19 or more file descriptors are currently open. [EMFILE] 


Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. , 


See Also 


sh(C), read(S), write(S), fork(S), popen(S) 
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Name 


plock — Lock process, text, or data in memory. 


Syntax 
#include <sys/lock.h> 
int plock (op) 
int op; 

Description 


Plock allows the calling process to lock its text segment (text lock), its data segment (data lock), or both 
its text and data segments (process lock) into memory. Locked segments are immune to all routine 
swapping. Plock also allows these segments to be unlocked. The effective user ID of the calling process 
must be root user to use this call. Op specifies the following: 


PROCLOCK 
Lock text and data segments into memory. 


TXTLOCK 
Lock text segment into memory. 


DATLOCK 
Lock data segment into memory. 


UNLOCK 
Remove all process locks. 


Plock will fail and not perform the requested operation if one or more of the following are true: 
The effective user ID of the calling process is not root. [EPERM] 


Op is equal to PROLOCK and a process lock, a text lock, or a data lock already exists on the calling 
process. [EINVAL] 


Op is equal to TXTLOCK and a text lock, or a process lock already exists on the calling process. 
[EINVAL] 


Op is equal to DATLOCK and a data lock, or a process lock already exists on the calling process. 
[EINVAL] 


Op is equal to UNLOCK and no type of lock exists on the calling process. [EINVAL] 


Return Value 


Upon successful completion, a value of 0 is returned to the calling process. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 


See Also 


exec(S), exit(S), fork(S) 
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Name 


popen, pclose — Initiates I/O to or from a process. 


Syntax 
#include <stdio.h> 


FILE *popen (command, type) 
char «command, «type; 


int pclose (stream) 
FILE *stream; 
Description 


The arguments to popen are pointers to null-terminated strings containing, respectively, a shell com- 
mand line and an I/O mode, either “r” for reading or “w” for writing. Popen creates a pipe between 
the calling process and the command to be executed. The value returned is a stream pointer that can be 
used (as appropriate) to write to the standard input of the command or read from its standard output. 


A stream opened by popen should be closed by pclose, which waits for the associated process to ter- 
minate and returns the exit status of the command. Because open files are shared between processes, a 


662.99 


type ‘“‘r” command may be used as an input filter, and a type “w” as an output filter. 


See Also 


pipe(S), wait(S), fclose(S), fopen(S), system(S) 


Diagnostics 
Popen returns a null pointer if files or processes cannot be created, or if the shell cannot be accessed. 


Pclose returns —1 if stream is not associated with a popened command. 


Notes 


Buffered reading before opening an input filter may leave the standard input of that filter mispositioned. 
Similar problems with an output filter may be forestalled by careful buffer flushing; see fclose(S). 
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Name 


c~ 


printf, fprintf, sprintf — Formats output. 


Syntax 
#include <stdio.h> 


int printf (format [| , arg |... ) 
char *format; 


int fprintf (stream, format [ , arg |... ) 
FILE *stream; 
char *format; 


int sprintf (s, format [| , arg]... ) 
char *s, format; 


Description 


Printf places output on the standard output stream stdout. Fprintf places output on the named output 
stream. Sprintf places output, followed by the null character (\0) in consecutive bytes starting at s; it is 
the user’s responsibility to ensure that enough storage is available. Each function returns the number of 
characters placed (not including the \O in the case of sprintf), or a negative value if an output error was 
encountered. 


Each of these functions converts, formats, and prints its args under control of the format. The format 

c~ is a character string that contains two types of objects: plain characters, which are simply copied to the 
output stream, and conversion specifications, each of which results in fetching of zero or more args. The 
results are undefined if there are insufficient args for the format. If the format is exhausted while args 
remain, the excess args are simply ignored. 


Each conversion specification is introduced by the character %. After the %, the following appear in 
sequence: 


Zero or more flags, which modify the meaning of the conversion specification. 


An optional decimal digit string specifying a minimum field width. If the converted value has fewer 
characters than the field width, it will be padded on the left (or right, if the left-adjustment flag 
described below has been given) to the field width. If the field width is preceded with a “O” (e.g., 
%04), the converted value will be padded with zeroes. If the width is preceded with a blank (e.g., 
% 4), the value will be preceded with blanks. Padding with zeroes may be applied to numeric 
conversions only. Strings and characters cannot be zero padded. 


A precision that gives the minimum number of digits to appear for the d, 0, u, x, or X conversions, 
the number of digits to appear after the decimal point for the e and f conversions, the maximum 
number of significant digits for the g conversion, or the maximum number of characters to be 
printed from a string in s conversion. The precision takes the form of a period (.) followed by a de- 
cimal digit string: a null digit string is treated as zero. 


An optional | specifying that a following d, 0, u, x, or X conversion character applies to a long in- 
teger arg. 


oo A character that indicates the type of conversion to be applied. 
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A field width or precision may be indicated by an asterisk (*) instead of a digit string. In this case, an 
integer arg supplies the field width or precision. The arg that is actually converted is not fetched until 
the conversion letter is seen, so the args specifying field width or precision must appear before the arg 
(if any) to be converted. 


The flag characters and their meanings are: 


blank 


The result of the conversion will be left-justified within the field. 
The result of a signed conversion will always begin with a sign (+ or —). 


If the first character of a signed conversion is not a sign, a blank will be prepended to the 
result. This implies that if the blank and + flags both appear, the blank flag will be ignored. 


This flag specifies that the value is to be converted to an “alternate form.” For c, d,s, and u 
conversions, the flag has no effect. For o conversion, it increases the precision to force the 
first digit of the result to be a zero. For x (X) conversion, a nonzero result will have 0x (0X) 
prepended to it. For e, E, f, g, and G conversions, the result will always contain a decimal 
point, even if no digits follow the point (normally, a decimal point appears in the result of 
these conversions only if a digit follows it). For g and G conversions, trailing zeroes will not 
be removed from the result (which they normally are). 


The conversion characters and their meanings are: 


d,o,u,x,X 


e,E 


% 
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The integer arg is converted to signed decimal, unsigned octal, decimal, or hexadecimal nota- 
tion (x and X), respectively; the letters abedef are used for x conversion and the letters 
ABCDEF for X conversion. The precision specifies the minimum number of digits to appear; 
if the value being converted can be represented in fewer digits, it will be expanded with 
leading zeroes. The default precision is 1. The result of converting a zero value with a pre- 
cision of zero is a null string (unless the conversion is 0, x, or X and the # flag is present). 


The float or double arg is converted to decimal notation in the style “[—]ddd.ddd”’, where 
the number of digits after the decimal point is equal to the precision specification. If the 
precision is missing, six digits are output; if the precision is explicitly 0, no decimal point ap- 
pears. 


The float or double arg is converted in the style 

“*[—]d.ddde+dd”’, where there is one digit before the decimal point and the number of digits 
after it is equal to the precision; when the precision is missing, 6 digits are produced; if the 
precision is zero, no decimal point appears. The E format code will produce a number with 
E instead of e introducing the exponent. The exponent always contains exactly two digits. 


The float or double arg is printed in style f or e (or in style E in the case of a G format 
code), with the precision specifying the number of significant digits. The style used depends 
on the value converted: style e will be used only if the exponent resulting from the conversion 
is less than —4 or greater than the precision. Trailing zeroes are removed from the result; a 
decimal point appears only if it is followed by a digit. 


The character arg is printed. 


The arg is taken to be a string (character pointer) and characters from the string are printed 
until a null character (\0) is encountered or the number of characters indicated by the pre- 
cision specification is reached. If the precision is missing, it is taken to be infinite, so all 
characters up to the first null character are printed. 


Print a %; no argument is converted. 
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In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion 
is wider than the field width, the field is simply expanded to contain the conversion result. Characters 
generated by printf and fprintf are printed as if putchar had been called (see putc(S)). 


Examples 


To print a date and time in the form “Sunday, July 3, 10:02”, where weekday and month are pointers 
to null-terminated strings: 


printf("%s, %s %d, %.2d:%.2d", weekday, month, day, hour, min); 
To print z to five decimal places: 


printf("pi = %.5f", 4*atan(1.0)); 


See Also 


ecvt(S), putc(S), scanf(S) 
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Name 


profil — Creates an execution time profile. 


Syntax 


profil (buff, bufsiz, offset, scale) 
char «buff; 

int bufsiz, scale; 

int (*offset)(); 


Description 


Buff points to an area of core whose length (in bytes) is given by bufsiz. After this call, the user’s pro- 
gram counter is examined each clock tick, where a clock tick is some fraction of a second given in 
machine(M). Offset is subtracted from it, and the result multiplied by scale. If the resulting number 
corresponds to a word inside buff, that word is incremented. 


The scale is interpreted as an unsigned, fixed-point fraction with binary point at the left: 0177777 
(octal) gives a 1-1 mapping of pc’s to words in buff; 077777 (octal) maps each pair of instruction words 
together. 02(octal) maps all instructions onto the beginning of buff (producing a noninterrupting core 
clock). 


Profiling is turned off by giving a scale of 0 or 1. It is rendered ineffective by giving a bufsiz of 0. 
Profiling is turned off when an exec is executed, but remains on in child and parent both after a fork. 
Profiling will be turned off if an update in buff would cause a memory fault. 


c 


See Also 


prof(CP), monitor(S) 
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Name 


PTRACE (S) 


ptrace — Traces a process. 


Syntax 


#include <sys/types.h> 


ptrace(request, pid, addr, data); 


Description 


Ptrace provides a means by which a parent process may control the execution of a child process. Its pri- 
mary use is in the implementation of breakpoint debugging; see adb(CP). The child process behaves 
normally until it encounters a signal (see signal(S) for the list), at which time it enters a stopped state 
and its parent is notified via wait(S). When the child is in the stopped state, its parent can examine and 
modify its “memory image” using ptrace. Also, the parent can cause the child either to terminate or 
continue, with the possibility of ignoring the signal that caused it to stop. 


The request argument determines the precise action to be taken by ptrace and is one of the following: 


0 


This request must be issued by the child process if it is to be traced by its parent. It turns 
on the child’s trace flag that stipulates that the child should be left in a stopped state upon 
receipt of a signal rather than the state specified by func; see signal(S). The pid, addr, 
and data arguments are ignored, and a return value is not defined for this request. Pecu- 
liar results will ensue if the parent does not expect to trace the child. 


The remainder of the requests can only be used by the parent process. For each, pid is the process ID of 
the child. The child must be in a stopped state before these requests are made. 


1,2 The word at location addr in the address space of the child is returned to the parent 


4,5 
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process. If I and D space are separated, request 1 returns a word from I space, and 
request 2 returns a word from D space. If I and D space are not separated, either request 
1 or request 2 may be used with equal results. The data argument is ignored. These two 
requests will fail if addr is not the start address of a word, in which case a value of —1 is 
returned to the parent process and the parent’s errno is set to EIO. 


With this request, the word at location addr in the child’s USER area in the system’s ad- 
dress space (see <sys/user.h>) is returned to the parent process. When executed in a 
segmented environment, sa_seg is ignored. The data argument is ignored. This request 
will fail if addr is not the start address of a word or is outside the USER area, in which 
case a value of —1 is returned to the parent process and the parent’s errno is set to EIO. 


With these requests, the value given by the data argument is written into the address 
space of the child at location addr. If I and D space are separated, request 4 writes a 
word into I space, and request 5 writes a word into D space. If I and D space are not 
separated, either request 4 or request 5 may be used with equal results. Upon successful 
completion, the value written into the address space of the child is returned to the parent. 
These two requests will fail if addr is a location in a pure procedure space and another 
process is executing in that space, or addr is not the start address of a word. Upon failure 
a value of —1 is returned to the parent process and the parent’s errno is set to EIO. 


With this request, a few entries in the child’s USER area can be written. Data gives the 
value that is to be written and addr is the location of the entry. The few entries that can 
be written follow: 
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—The general registers 
—Any floating-point status registers 


This request causes the child to resume execution. If the data argument is 0, all pending 
signals including the one that caused the child to stop are canceled before it resumes exe- 
cution. If the data argument is a valid signal number, the child resumes execution as if it 
had incurred that signal and any other pending signals are canceled. The addr must be 
(int*)1. Upon successful completion, the value of data is returned to the parent. This 
request will fail if data is not 0 or a valid signal number, in which case a value of —1 is 
returned to the parent process and the parent’s errno is set to EIO. 


This request causes the child to terminate with the same consequences as exit(S). 


Execution continues as in request 7; however, as soon as possible after execution of at least 
one instruction, execution stops again. The signal number from the stop is SIGTRAP. 
This is part of the mechanism for implementing breakpoints. The exact implementation 
and behavior is somewhat CPU dependent. 


As indicated, these calls (except for request 0) can be used only when the subject process has 
stopped. The wait system call is used to determine when a process stops; in such a case the ter- 
mination status returned by wait has the value 0177 to indicate stoppage rather than genuine 
termination. 


To prevent security violations, ptrace inhibits the set-user-id facility on subsequent exec(S) 
calls. If a traced process calls exec, it will stop before executing the first instruction of the new 
image showing signal SIGTRAP. 


Errors 


Ptrace will in general fail if one or more of the following are true: 


Request is an illegal number. [EIO] 


Pid identifies a child that does not exist or has not executed a ptrace with request 0. [ESRCH] 


A return value of —1 does not always indicate an error. To resolve this ambiguity, the errno variable is 
cleared on each call to ptrace. If the return value is —1, there is no error unless errno is nonzero. 


Notes 


The implementation and precise behavior of this system call is inherently tied to the specific CPU and 
process memory model in use on a particular machine. Code using this call is likely to not be portable 
across all implementations without some change. 


System calls cannot be single-stepped. 


See Also 


adb(CP), exec(S), signal(S), wait(S), machine(M) 
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Name 


putc, putchar, fputc, putw — Puts a character or word on a stream. 


Syntax 
#include <stdio.h> 
int putc (c, stream) 
char c; 
FILE *stream; 
putchar (c) 


int fputc (c, stream) 
FILE *stream; 


int putw (w, stream) 
int w; 
FILE *stream; 
Description 
Putc appends the character c to the named output stream. It returns the character written. 
Putchar(c) is defined as putc(c,stdout ). 


Fputc behaves like putc, but is a genuine function rather than a macro; it may therefore be used as an 
argument. Fputc runs more slowly than putc, but takes less space per invocation. 


Putw appends the word (i.e., integer) w to the output stream. Putw neither assumes nor causes special 
alignment in the file. 


The standard stream stdout is normally buffered if and only if the output does not refer to a terminal; 
this default may be changed by setbuf(S). The standard stream stderr is by default unbuffered uncon- 
ditionally, but use of freopen (see fopen(S)) will cause it to become unbuffered; setbuf, again, will set 
the state to whatever is desired. When an output stream is unbuffered information appears on the des- 
tination file or terminal as soon as written; when it is buffered many characters are saved up and written 
as a block. See fflush is fclose(S). 


See Also 
fclose(S), ferror(S), fopen(S), fread(S), getc(S), printf(S), puts(S) 
Diagnostics 
These functions return the constant EOF upon error. Since this is a valid integer, ferror(S) should be 


used to detect putw errors. 


Notes 


Because putc is implemented as a macro, the stream argument with side effects is not treated correctly. 
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Name 


putpwent — Writes a password file entry. 


Syntax 
#include <pwd.h> 


int putpwent (p, f) 

struct passwd *«p; 

FILE +f; 
Description 


Putpwent is the inverse of getpwent(S). Given a pointer to a passwd structure created by getpwent (or 
getpwuid or getpwnam), putpwent writes a line on the stream f. The line matches the format of 
/etc/passwd. 


See Also 


passwd(M), getpwent(S) 


Diagnostics 


Putpwent returns nonzero if an error was detected during its operation, otherwise zero. 
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Name 


puts, fputs — Puts a string on a stream. 


Syntax 
#include <stdio.h> 


int puts (s) 
char *s; 


int fputs (s, stream) 
char *s; 
FILE *stream; 


Description 


Puts copies the null-terminated string s to the standard output stream stdout and appends a newline 
character. 


Fputs copies the null-terminated string s to the named output stream. 


Neither routine copies the terminating null character. 


Diagnostics 


Both routines return EOF on error. 


See Also 


ferror(S), fopen(S), fread(S), gets(S), printf(S), putc(S) 


Notes 


Puts appends a newline, fputs does not. 
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Name 


qsort — Performs a sort. 


Syntax 


qsort (base, nel, width, compar) 
char *base; 

int nel, width; 

int (*compar)( ); 


Description 


Qsort is an implementation of the quicker-sort algorithm. The first argument is a pointer to the base of 
the data; the second is the number of elements; the third is the width of an element in bytes; the last is 
the name of the comparison routine. It is called with two arguments which are pointers to the elements 
being compared. The routine must return an integer less than, equal to, or greater than 0 according to 
how much the first argument is to be considered less than, equal to, or greater than the second. 


See Also 


sort(C), bsearch(S), lsearch(S), string(S) 
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Name 


rand, srand — Generates a random number. 


Syntax 


srand (seed) 
unsigned seed; 


int rand ( ) 


Description 


Rand uses a multiplicative congruential random number generator with period 2°” to return successive 
pseudo-random numbers in the range from 0 to 2°. 


The generator is reinitialized by calling srand with 1 as argument. It can be set to a random starting 
point by calling srand with an unsigned integer in argument seed. 
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Name 


rdchk — Checks to see if there is data to be read. 


Syntax 
rdchk(fdes); 
int fdes; 

Description 


Rdchk checks to see if a process will block if it attempts to read the file designated by fdes. Rdchk re- 
turns | if there is data to be read or if it is the end of the file (EOF). In this context, the proper se- 
quence of calls using rdchk is: 


if(rdchk(fildes) > 0) 
read(fildes, buffer, nbytes); 
See Also 


read(S) 


Diagnostics 


Rdchk returns -1 if an error occurs (e.g., EBADF), 0 if the process will block if it issues a read and 1 if 
it is okay to read. EBADF is returned if a rdchk is done on a semaphore file or if the file specified 
doesn’t exist. 


Notes 


This function may be linked with the linker option - Ix. 
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Name 


read — Reads from a file. 


Syntax 


int read (fildes, buf, nbyte) 
int fildes; 

char «buf; 

unsigned nbyte; 


Description 


Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system call. 
Read attempts to read nbyte bytes from the file associated with fildes into the buffer pointed to by buf. 


On devices capable of seeking, the read starts at a position in the file given by the file pointer associated 
with fildes. Upon return from read, the file pointer is incremented by the number of bytes actually 
read. 


Devices that are incapable of seeking always read from the current position. The value of a file pointer 
associated with such a file is undefined. 


Upon successful completion, read returns the number of bytes actually read and placed in the buffer; 
this number may be less than nbyte if the file is associated with a communication line (see ioct/(S) and 
tty(M)), or if the number of bytes left in the file is less than nbyte bytes. A value of 0 is returned when 
an end-of-file has been reached. 


When attempting to read from an empty pipe (or FIFO): 
If O NDELAY is set, the read will return a 0. 


If O NDELAY is clear, the read will block until data is written to the file or the file is no longer 
open for writing. 


When attempting to read a file associated with a tty that has no data currently available: 
If O NDELAY is set, the read will return a 0. 
If O NDELAY is clear, the read will block until data becomes available. 

Read will fail if one or more of the following are true: 
Fildes is not a valid file descriptor open for reading. [EBADF] 


Buf points outside the allocated address space. [EFAULT] 


Return Value 


Upon successful completion a nonnegative integer is returned indicating the number of bytes actually 
read. Otherwise, a —1 is returned and errno is set to indicate the error. 


See Also 


creat(S), dup(S), fentl(S), ioctl(S), open(S), pipe(S), tty(M) 
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Notes 


Reading a region of a file locked with locking or lockf causes read to hang indefinitely until the locked Uo 
region is unlocked. 
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Name 


regex, regcmp — Compiles and executes regular expressions. 


Syntax 


char +regcmp(string1|[,string2, ...],0); 
char *string1, *string2, ...; 


char +regex(re,subject|,ret0, ...]); 
char re, *subject, *ret0, ...; 


Description 


Regcmp compiles a regular expression and returns a pointer to the compiled form. Malloc(S) is used to 
create space for the vector. It is the user’s responsibility to free unneeded space so allocated. A zero re- 
turn from regcmp indicates an incorrect argument. Regcmp(S) has been written to generally preclude 
the need for this routine at execution time. 


Regex executes a compiled pattern against the subject string. Additional arguments are passed to re- 
ceive values back. Regex returns zero on failure or a pointer to the next unmatched character on 
success. A global character pointer Jocl points to where the match began. Regcmp and regex were 
derived from the editor, ed(C) however, the syntax and semantics have been changed slightly. The fol- 
lowing are the valid symbols and their associated meanings. 


[]*.° | These symbols retain their current meaning. 
$ Matches the end of the string, \n matches the newline. 


= Within brackets the minus means through. For example, [a—z] is equivalent to [abcd...xyz]. 
The — can appear as itself only if used as the last or first character. For example, the character 
class expression []—] matches the characters ] and —. 


7 A regular expression followed by + means "one or more times". For example, [0—9]+ is 
equivalent to [0—9][0—9]«. 


{m} {m,} {m,uj 
Integer values enclosed in {} indicate the number of times the preceding regular expression is to 
be applied. m is the minimum number and u is a number, less than 256, which is the max- 
imum. If only m is present (e.g., {m}), it indicates the exact number of times the regular ex- 
pression is to be applied. {m,} is analogous to {m,infinity}. The plus (+) and star (*) operations 
are equivalent to {1,} and {0,} respectively. 


(... )$n The value of the enclosed regular expression is to be returned. The value will be stored in the 
(n+1)th argument following the subject argument. At present, at most ten enclosed regular ex- 
pressions are allowed. Regex makes its assignments unconditionally. 


(...) Parentheses are used for grouping. An operator, e.g. *, +, {}, can work on a single character or 
a regular expression enclosed in parenthesis. For example, (a*(cb+)*)$0. 


By necessity, all the above defined symbols are special. They must, therefore, be escaped to be used as 
themselves. 
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Examples 


Example 1: 
char *cursor, *newcursor, «ptr; 


newcursor = regex((ptr=regcmp(""\n",0)),cursor); 
free(ptr); 


This example will match a leading newline in the subject string pointed at by cursor. 


Example 2: 


char ret0[9]; 
char *newcursor, *name; 


name = regemp("([A—Za—z][A—za—z0—9_]{0,7})$0",0); 
newcursor = regex(name,"123Testing321",ret0); 


This example will match through the string ““Testing3” and will return the address of the character after 
the last matched character (cursort+11). The string “Testing3’ will be copied to the character array 
ret0. 


Example 3: 
#include "file.i" 
char *string, *newcursor; 


newcursor = regex(name;,string); 


This example applies a precompiled regular expression in file.i (see regcemp(C)) against string. 


See Also 


ed(C), regemp(CP), free(S), malloc(S) 


Notes 


The user program may run out of memory if regcmp is called iteratively without freeing the vectors no 
longer required. The following user-supplied replacement for malloc(S) reuses the same vector saving 
time and space: 


/* user’s program */ 
malloc(n) 


static int rebuf[256]; 
return &rebuf; 
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Name 


REGEXP (S) 


regexp — Regular expression compile and match routines. 


Syntax 


#define INIT <declarations> 

#define GETC() <getc code> 

#define PEEKC() <peekc code> 

#define UNGETC(c) <ungetc code> 
#define RETURN(pointer) <return code> 
#define ERROR(val) <error code> 


#include <regexp.h> 


char *compile(instring, expbuf, endbuf, eof) 
char *instring, *expbuf, «endbuf; 


int step(string, expbuf) 
char *string, *expbuf; 


Description 


This page describes general purpose regular expression matching routines in the form of ed(C), defined 
in /usr/include/regexp.h. Programs such as ed(C), sed(C), grep(C), expr(C), etc., which perform re- 
gular expression matching use this source file. In this way, only this file need be changed to maintain 


regular expression compatibility. 


The interface to this file is unpleasantly complex. Programs that include this file must have the fol- 
lowing five macros declared before the “#include <regexp.h>” statement. These macros are used by 


the compile routine. 


GETC() 


PEEKC() 


UNGETC(c) 


RETURN (pointer) 


ERROR(val/) 
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Return the value of the next character in the regular expression pattern. Succes- 
sive calls to GETC() should return successive characters of the regular expres- 
sion. 


Return the next character in the regular expression. Successive calls to PEEKC() 
should return the same character (which should also be the next character re- 
turned by GETC()). 


Cause the argument c to be returned by the next call to GETC() (and PEEKC()). 
No more than one character of pushback is ever needed and this character is 
guaranteed to be the last character read by GETC(). The value of the macro 
UNGETC(c) is always ignored. 


This macro is used on normal exit of the compile routine. The value of the argu- 
ment pointer is a pointer to the character after the last character of the compiled 
regular expression. This is useful to programs which have memory allocation to 
manage. 


This is the abnormal return from the compile routine. The argument val is an 
error number (see table below for meanings). This call should never return. 
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ERROR MEANING 

11 Range endpoint too large. we, 
16 Bad number. 

25 ‘\digit” out of range. 

36 Illegal or missing delimiter. 

4] No remembered search string. 

42 \( \) imbalance. 

43 Too many \(. 

44 More than 2 numbers given in \{ \}. 
45 } expected after \. 

46 First number exceeds second in \{ \}. 
49 [ ] imbalance. 

50 Regular expression overflow. 


The syntax of the compile routine is as follows: 
compile(instring, expbuf, endbuf, eof) 


The first parameter instring is never used explicitly by the compile routine but is useful for programs 
that pass down different pointers to input characters. It is sometimes used in the INIT declaration (see 
below). Programs which call functions to input characters or have characters in an external array can 
pass down a value of ((char *) 0) for this parameter. 


The next parameter expbuf is a character pointer. It points to the place where the compiled regular ex- 
pression will be placed. 


The parameter endbuf is one more that the highest address that the compiled regular expression may be 
placed. If the compiled expression cannot fit in (endbuf—expbuf) bytes, a call to ERROR(50) is made. 


The parameter eof is the character which marks the end of the regular expression. For example, in 
ed(C), this character is usually a /. 


Each program that includes this file must have a #define statement for INIT. This definition will be 
placed right after the declaration for the function compile and the opening curly brace ({ ). It is used 
for dependent declarations and initializations. Most often it is used to set a register variable to point to 
the beginning of the regular expression so that this register variable can be used in the declarations for 
GETC(), PEEKC() and UNGETC(). Otherwise it can be used to declare external variables that might 
be used by GETC(), PEEKC() and UNGETC(). See the example below of the declarations taken from 


grep(C). 


There are other functions in this file which perform actual regular expression matching, one of which is 
the function step. The call to step is as follows: 


step(string, expbuf) 


The first parameter to step is a pointer to a string of characters to be checked for a match. This string 
should be null terminated. 


The second parameter expbuf is the compiled regular expression which was obtained by a call of the 
function compile. 


The function step returns one, if the given string matches the regular expression, and zero if the expres- 

sions do not match. If there is a match, two external character pointers are set as a side effect to the 

call to step. The variable set in step is locl. This is a pointer to the first character that matched the 

regular expression. The variable /oc2, which is set by the function advance, points to the character after 

the last character that matches the regular expression. Thus if the regular expression matches the entire , 
line, locl will point to the first character of string and Joc2 will point to the null at the end of string. 
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Step uses the external variable circf which is set by compile if the regular expression begins with ~. If 
this is set then step will only try to match the regular expression to the beginning of the string. If more 
than one regular expression is to be compiled before the the first is executed, the value of circf should be 
saved for each compiled expression and circf should be set to that saved value before each call to step. 


The function advance is called from step with the same arguments as step. The purpose of step is to 
step through the string argument and call advance until advance returns a one indicating a match, or 
until the end of string is reached. If one wants to constrain string to the beginning of the line in all 
cases, step need not be called; simply call advance. 


When advance encounters a * or \{ \} sequence in the regular expression it will advance its pointer to 
the string to be matched as far as possible, and will recursively call itself trying to match the rest of the 
string to the rest of the regular expression. As long as there is no match, advance will back up along 
the string until it finds a match, or reaches the point in the string that initially matched the * or \{ \}. 
It is sometimes desirable to stop this backing up before the initial point in the string is reached. If the 
external character pointer Jocs is equal to the point in the string at sometime during the backing up 
process, advance will break out of the loop that backs up and will return zero. This is used by ed(C) 
and sed(C) for substitutions done globally (not just the first occurrence, but the whole line) so, for ex- 
ample, expressions like s/y*//g do not loop forever. 


The routines ecmp and getrange are trivial and are called by the routines previously mentioned. 


Examples 


The following is an example of how the regular expression macros and calls look from grep(C): 


#define INIT register char *sp = instring; 
#define GETC() (*sp++) 

#define PEEKC( ) (*sp) 

#define UNGETC(c) (=—=sp) 

#define RETURN(c) return; 

#define ERROR(c) regerr() 


#include <regexp.h> 
compile(*argv, expbuf, &expbuf[ESIZE], ‘\0'); 


if(step(linebuf, expbuf)) 
succeed( ); 


Files 


/usr/include/regexp.h 


See Also 


ed(C), grep(C), sed(C). 
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Notes 
The handling of circf is awkward. 


The routine ecmp is equivalent to the Standard I/O routine strncmp and should be replaced by that 
routine. 
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Name 


sbrk — Changes data segment space allocation. 


Syntax 
char *sbrk (incr) 
int incr; 
Description 


Sbrk is used to dynamically change the amount of space allocated for the calling process’ data segment; 
see exec(S). The change is made by resetting the process’ break value. The break value is the address 
of the first location beyond the end of the data segment. The amount of allocated space increases as the 
break value increases. 


Sbrk adds incr bytes to the break value and changes the allocated space accordingly. Incr can be nega- 
tive, in which case the amount of allocated space is decreased. 


Sbrk will fail without making any change in the allocated space if such a change would result in more 
space being allocated than is allowed by a system-imposed maximum (see ulimit(S)). [ENOMEM] 
Return Value 
Upon successful completion, sbrk returns the old break value. Otherwise, a value of —1 is returned and 
errno is set to indicate the error. 
See Also 


exec(S) 
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Name 


scanf, fscanf, sscanf — Converts and formats input. 


Syntax 


#include <stdio.h> 


int scanf (format [ , pointer]... ) 
char *format; 


int fscanf (stream, format [ , pointer]... ) 
FILE *stream; 
char *format; 


int sscanf (s, format [ , pointer |... ) 
char *s, *format; 


Description 


Scanf reads from the standard input stream stdin. Fscanf reads from the named input stream. Sscanf 
reads from the character string s. Each function reads characters, interprets them according to a 
format, and stores the results in its arguments. Each expects, as arguments, a control string format 
described below, and a set of pointer arguments indicating where the converted input should be stored. 


The control string usually contains conversion specifications, which are used to direct interpretation of 
input sequences. The control string may contain: 


1. Blanks, tabs, or newlines, which cause input to be read up to the next nonwhitespace character. 
2. An ordinary character (not %), which must match the next character of the input stream. 


3. Conversion specifications, consisting of the character %, an optional assignment suppressing 
character *, an optional numerical maximum field width, and a conversion character. 


A conversion specification directs the conversion of the next input field; the result is placed in the vari- 
able pointed to by the corresponding argument, unless assignment suppression was indicated by *. An 
input field is defined as a string of nonspace characters; it extends to the next inappropriate character or 
until the field width, if specified, is exhausted. 


The conversion character indicates the interpretation of the input field; the corresponding pointer argu- 
ment must usually be of a restricted type. The following conversion characters are allowed: 


% A single % is expected in the input at this point; no assignment is done. 

d A decimal integer is expected; the corresponding argument should be an integer pointer. 

o An octal integer is expected; the corresponding argument should be an integer pointer. 

x A hexadecimal integer is expected; the corresponding argument should be an integer pointer. 


s Acharacter string is expected; the corresponding argument should be a character pointer pointing to 
an array of characters large enough to accept the string and a terminating \0, which will be added 
automatically. The input field is terminated by a space character or a newline. 


c A character is expected; the corresponding argument should be a character pointer. The normal 
skip over space characters is suppressed in this case; to read the next nonspace character, use % Is. 
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If a field width is given, the corresponding argument should refer to a character array; the indicated 
number of characters is read. 


A floating-point number is expected; the next field is converted accordingly and stored through the 
corresponding argument, which should be a pointer to a float. The input format for floating-point 
numbers is an optionally signed string of digits, possibly containing a decimal point, followed by an 
optional exponent field consisting of an E or an e, followed by an optionally signed integer. 


Indicates a string that is not to be delimited by space characters. The left bracket is followed by a 
set of characters and a right bracket; the characters between the brackets define a set of characters 
making up the string. If the first character is not a caret (“), the input field consists of all charac- 
ters up to the first character that is not in the set between the brackets; if the first character after 
the left bracket is a “, the input field consists of all characters up to the first character that is in the 
set of the remaining characters between the brackets. The corresponding argument must point to a 
character array. 


conversion characters d, 0, and x may be capitalized and/or preceded by | to indicate that a pointer 


to long rather than to int is in the argument list. Similarly, the conversion characters e and f may be 
capitalized and/or preceded by I to indicate that a pointer to double rather than to float is in the argu- 


men 


t list. The character h will, some time in the future, indicate short data items. 


Scanf conversion terminates at EOF, at the end of the control string, or when an input character 
conflicts with the control string. In the latter case, the offending character is left unread in the input 
stream. ®This is very important to remember, because subtle errors can occur when not taking this into 
account. 


Scanf returns the number of successfully matched and assigned input items; this number can be zero in 
the event of an early conflict between an input character and the control string. If the input ends before 
the first conflict or conversion, EOF is returned. 


Examples 


The 


call: 


int 1; float x; char name[50]; 
scanf ("%d%f%s", &i, &x, name); 


with the input line: 


will 


with 


will 
(see 


See Also 


25 54.32E—1 thompson 
assign to i the value 25, to x the value 5.432, and name will contain thompson\0. Or: 


int i; float x; char name[50]; 
scanf ("%2d%f%+d%[1234567890|", &i, &x, name); 


input: 
56789 0123 56a72 


assign 56 to i, 789.0 to x, skip 0123, and place the string 56\0 in name. The next call to getchar 
getc(S)) will return a. 


atof(S), getc(S), printf(S) 
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Diagnostics 


These functions return EOF on end of input and a short count for missing or illegal data items. 


Notes 
The success of literal matches and suppressed assignments is not directly determinable. 


Trailing whitespace (including a newline) is left unread unless matched in the control string. 
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Name 


sdenter, sdleave — Synchronizes access to a shared data segment. 


Syntax 


#include <sd.h> 


int sdenter(addr,flags) 
char *addr; 
int flags; 


int sdleave(addr) 
char *addr; 


Description 


Sdenter is used to indicate that the current process is about to access the contents of a shared data seg- 
ment. The actions performed depend on the value of flags. Flags values are formed by OR-ing together 
entries from the following list: 


SD NOWAIT _ If another process has called sdenter but not sdleave for the indicated segment, and the 
segment was not created with the SD UNLOCK flag set, return an ENAVAIL error in- 
stead of waiting for the segment to become free. 


SD_WRITE Indicates that the process wants to write data to the shared data segment. A process 
that has attached to a shared data segment with the SD RDONLY flag set will not be al- 
lowed to enter with the SD WRITE flag set. 


Sdleave is used to indicate that the current process is done modifying the contents of a shared data seg- 
ment. 


Only changes made between invocatations of sdenter and sdleave are guaranteed to be reflected in other 
processes. Sdenter and sdleave are very fast; consequently, it is recommended that they be called fre- 
quently rather than leave sdenter in effect for any period of time. In particular, system calls should be 
avoided between sdenter and sdleave calls. 


The fork system call is forbidden between calls to sdenter and sdleave if the segment was created 
without the SD UNLOCK flag. 


Return Value 


Successful calls return 0. Unsuccessful calls return -1, and errno is set to indicate the error. Errno is set 
to EINVAL if a process does an sdenter with the SD_WRITE flag set and the segment is already attached 
with the SD RDONLY flag set. Errno is set to ENAVAIL if the SD NOWAIT flag is set for sdenter call 
and the shared data segment is not free. 


See Also 


sdget(S), sdgetv(S) 
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Notes , 
This feature is a XENIX specific enhancement and may not be present on all UNIX implementations. Uo 
This routine may be linked with the linker option - Ix. 
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Name 


sdget, sdfree — Attachs and detachs a shared data segment. 


Syntax 


#include <sd.h> 


char *sdget(path, flags, [size, mode]) 
char *path; 

int flags, mode; 

long size; 


int sdfree(addr); 
char *addr; 


Description 


Sdget attachs a shared data segment to the data space of the current process. The actions performed 
are controlled by the value of flags. Flags values are constructed by OR-ing flags from the following 
list: 


SD RDONLY 
Attach the segment for reading only. 


SD WRITE Attach the segment for both reading and writing. 


SD CREAT If the segment named by path exists and is not in use (active), this flag will have the same 
effect as creating a segment from scratch. Otherwise, the segment is created according to 
the values of size and mode. Read and write access to the segment is granted to other pro- 
cesses based on the permissions passed in mode, and functions the same as those for re- 
gular files. Execute permission is meaningless. The segment is initialized to contain all 
zeroes. 


SD UNLOCK 
If the segment is created because of this call, the segment will be made so that more than 
one process can be between sdenter and sdleave calls. 


Sdfree detachs the current process from the shared data segment that is attached at the specified ad- 
dress. If the current process has done an sdenter but not a sdleave for the specified segment, an sdleave 
will be done before detaching the segment. 


When no process remains attached to the segment, the contents of that segment disappear, and no 
process can attach to the segment without creating it by using the SD_CREAT flag in sdget. Errno is set 
to EEXIST if a process tries to create a shared data segment that exists and is in use. Errno is set to 
ENOTNAM if a process attempts an sdget on a file that exists but is not a shared data type. 


Notes 


Use of the SD UNLOCK flag on systems without hardware support for shared data may cause severe 
performance degradation. 


Sdget automatically increments the process’s original break value to the memory location immediately 
after the shared data segment. This affects subsequent sbrk or brk calls which attempt to restore the 
original break value. In particular, attempts to restore the break value to its value before the sdget call 
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will cause an error. 


This feature is a XENIX specific enhancement and may not be present in all UNIX implementations. 
This routine may be linked using the linker option - Ix. 


Return Value 


On successful completion, the address at which the segment was attached is returned. Otherwise, -1 is 
returned, and errno is set to indicate the error. Errno is set to EINVAL if a process does an sdget on a 
shared data segment to which it is already attached. Errno is set to EEXIST if a process tries to create 
a shared data segment that exists and is in use. Errno is set to ENOTNAM if a process attempts an 
sdget on a file that exists but is not a shared data type. 


See Also 


sdenter(S), sdgetv(S), sbrk(S) 
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Name 


sdgetv, sdwaitv — Synchronizes shared data access. 


Syntax 


#include <sd.h> 


int sdgetv(addr) 

int sdwaitv(addr, vnum) 
char *addr; 

int vnum; 


Description 


Sdgetv and sdwaitv may be used to synchronize cooperating processes that are using shared data seg- 
ments. The return value of both routines is the version number of the shared data segment attached to 
the process at address addr. The version number of a segment changes whenever some process does an 
sdleave for that segment. 


Sdgetv simply returns the version number of the indicated segment. 
Sdwaitv forces the current process to sleep until the version number for the indicated segment is no 
longer equal to vnum. 

Return Value 


Upon successful completion, both sdgetv and sdwaitv return a positive integer that is the current version 
number for the indicated shared data segment. Otherwise, a value of -1 is returned, and errno is set to 
indicate the error. 


See Also 
sdenter(S), sdget(S) 
Notes 


This routine may be linked using the linker option -lx. 


September 7, 1984 Page 1 


SETBUF (S) SETBUF (S) 


Name 


setbuf — Assigns buffering to a stream. 


Syntax 
#include <stdio.h> 


setbuf (stream, buf) 
FILE *stream; 
char *buf; 


Description 


Setbuf is used after a stream has been opened but before it is read or written. It causes the character 
array buf to be used instead of an automatically allocated buffer. If buf is the constant pointer NULL, 
input/output will be completely unbuffered. 


A manifest constant BUFSIZ tells how big an array is needed: 
char buf[BUFSIZ]; 


A buffer is normally obtained from malloc(S) upon the first getc(S) or putc(S) on the file, except that 
output streams directed to terminals, and the standard error stream stderr are normally not buffered. 


A common source of error is allocation of buffer space as an “automatic” variable in a code block, and 
then failing to close the stream in the same block. 


See Also 


fopen(S), getc(S), malloc(S), putc(S) 
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c™ Name 


setjmp, longjmp — Performs a nonlocal “goto”’. 


Syntax 
#include <setjmp.h> 


int setjmp (envy) 
jmp _buf env; 


int longjmp (envy, val) 
jmp _buf envy; 
Description 


These routines are useful for dealing with errors and interrupts encountered in a low-level subroutine of 
a program. 


Setjmp saves its stack environment in env for later use by Jongjmp. It returns value 0. 


Longjmp restores the environment saved by the last call of setjmp. It then returns in such a way that 

execution continues as if the call of setjmp had just returned the value val to the corresponding call to 

setjmp. The routine which calls setjmp must not itself have returned in the interim. Longjmp cannot 

return the value 0. If /Jongjmp is invoked with a second argument of 0, it will return 1. All accessible 

data have values as of the time /ongjmp was called. The only exception to this are register variables. 
o™ The value of register variables are undefined in the routine that called setjmp when the corresponding 
wy longjmp is invoked. 


See Also 


signal(S) 
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Name 


setpgrp — Sets process group ID. 


Syntax 


int setpgrp () 


Description 


Setpgrp sets the process group ID of the calling process to the process ID of the calling process and re- 
turns the new process group ID. 


Return Value 


Setpgrp returns the value of the new process group ID. 


See Also 


exec(S), fork(S), getpid(S), intro(S), kill(S), signal(S) 
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Name 


setuid, setgid — Sets user and group IDs. 


Syntax 


int setuid (uid) 
int uid; 


int setgid (gid) 
int gid; 
Description 
Setuid is used to set the real user ID and effective user ID of the calling process. 
Setgid is used to set the real group ID and effective group ID of the calling process. 


If the effective user ID of the calling process is super-user, the real user (group) ID and effective user 
(group) ID are set to uid (gid). 


If the effective user ID of the calling process is not super-user, but its real user (group) ID is equal to 
uid (gid), the effective user (group) ID is set to uid (gid). 


Setuid will fail if the real user (group) ID of the calling process is not equal to uid (gid) and its effec- 
tive user ID is not super-user. [EPERM] 
Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


getuid(S), intro(S) 
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Name 


shutdn — Flushes block I/O and halts the CPU. 


Syntax 
#include <sys/filsys.h> 
shutdn (sblk) 
struct filsys *sblk; 
Description 


Shutdn causes all information in core memory that should be on disk to be written out. This includes 
modified super-blocks, modified inodes, and delayed block I/O. The super-blocks of all writable file sys- 
tems are flagged ‘clean’, so that they can be remounted without cleaning when XENIX is rebooted. 
Shutdn then prints ‘““Normal System Shutdown” on the console and halts the CPU. 


If sblk is nonzero, it specifies the address of a super-block which will be written to the root device as the 
last I/O before the halt. This facility is provided to allow file system repair programs to supercede the 
system’s copy of the root super-block with one of their own. 


Shutdn locks out all other processes while it is doing its work. However, it is recommended that user 
processes be killed off (see kill(S)) before calling shutdn as some types of disk activity could cause file 
systems to not be flagged “‘clean’’. 


The caller must be the super-user. 


See Also 


fsck(C), haltsys(C), shutdown(C), mount(S), kill(S) 


Notes 


This routine may be linked using the linker option - Ix. 
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Name 


signal — Specifies what to do upon receipt of a signal. 


Syntax 
#include <signal.h> 
int (*signal (sig, func)) ) 
int sig; 
int (*func) ); 
Description 


Signal allows the calling process to choose one of three ways in which it is possible to handle the receipt 
of a specific signal. Sig specifies the signal and func specifies the choice. 


Sig can be assigned any one of the following except SIGKILL: 


SIGHUP 01 Hangup 


SIGINT 02 Interrupt 

SIGQUIT 03* Quit 

SIGILL 04* Illegal instruction (not reset when caught) 
SIGTRAP 05* _ Trace trap (not reset when caught) 
SIGIOT 06* I/O trap instruction 


SIGEMT 07* Emulator trap instruction 

SIGFPE 08* Floating-point exception 

SIGKILL 09 Kill (cannot be caught or ignored) 
SIGBUS 10* ‘Bus error 

SIGSEGV 11* Segmentation violation 

SIGSYS 12* Bad argument to system call 
SIGPIPE 13 Write on a pipe with no one to read it 
SIGALRM_ 14 Alarm clock 

SIGTERM 15 Software termination signal 
SIGUSRI1 16 User-defined signal 1 

SIGUSR2 17 User-defined signal 2 

SIGCLD 18 Death of a child (see Warning below) 
SIGPWR 19 Power fail (see Warning below) 


See number 7 below for the significance of the asterisk in the above list. 


Func is assigned one of three values: SIG DFL, SIG_IGN, or a function address. The actions prescribed 
by these values of are described below. 


The SIG_DFL value causes termination of the process upon receipt of a signal. Upon receipt of the 
signal sig, the receiving process is to be terminated with the following consequences: 


1. All of the receiving process’ open file descriptors will be closed. 


2. If the parent process of the receiving process is executing a wait, it will be notified of the termina- 
tion of the receiving process and the terminating signal’s number will be made available to the 
parent process; see wait(S). 


3. If the parent process of the receiving process is not executing a wait, the receiving process will be 
transformed into a zombie process (see exit(S) for definition of zombie process). 
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The parent process ID of each of the receiving process’ existing child processes and zombie processes 
will be set to 1. This means the initialization process (see intro(S)) inherits each of these processes. 


An accounting record will be written on the accounting file if the system’s accounting routine is en- 
abled; see acct(S). 


If the receiving process’ process ID, tty group ID, and process group ID are equal, the signal 
SIGHUP will be sent to all of the processes that have a process group ID equal to the process group 
ID of the receiving process. 


A “core image’”’ will be made in the current working directory of the receiving process if sig is one 
for which an asterisk (*) appears in the above list and the following conditions are met: 


— The effective user ID and the real user ID of the receiving process are equal. 


— An ordinary file named core exists and is writable or can be created. If the file must be created, 
it will have a mode of 0666 modified by the file creation mask (see umask(S)), a file owner ID that 
is the same as the effective user ID of the receiving process, a file group ID that is the same as the 
effective group ID of the receiving process 


The SIG_IGN value causes the process to ignore a signal. The signal sig is to be ignored. Note that the 
signal SIGKILL cannot be ignored. 


A function address value causes to process to catch a signal. Upon receipt of the signal sig, the re- 
ceiving process is to execute the signal-catching function pointed to by func. The signal number sig will 
be passed as the only argument to the signal-catching function. There are the following consequences: 


l. 


2 


Upon return from the signal-catching function, the receiving process will resume execution at the 
point it was interrupted and the value of func for the caught signal will be set to SIG_DFL unless 
the signal is SIGILL, SIGTRAP, SIGCLD, or SIGPWR. 


When a signal that is to be caught occurs during a read, a write, an open, or an ioctl system call 
on a slow device (like a terminal; but not a file), during a pause system call, or during a wait 
system call that does not return immediately due to the existence of a previously stopped or zombie 
process, the signal catching function will be executed and then the interrupted system call will re- 
turn a —1 to the calling process with errno set to EINTR. 


Note that the signal SIGKILL cannot be caught. 


A call to signal cancels a pending signal sig except for a pending SIGKILL signal. 


Signal will fail if one or more of the following are true: 


Sig is an illegal signal number, including SIGKILL. [EINVAL] 


Func points to an illegal address. [EFAULT] 


Return Value 


Upon successful completion, signal returns the previous value of func for the specified signal sig. Oth- 
erwise, a value of —1 is returned and errno is set to indicate the error. 


See Also 


kill(C), kill(S), pause(S), ptrace(S), wait(S), setjmp(S). 
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Warning 


Two other signals that behave differently than the signals described above exist in this release of the 
system; they are: 


SIGCLD 18 Death of a child (not reset when caught) 
SIGPWR 19 Power fail (not reset when caught) 


There is no guarantee that, in future releases of XENIX, these signals will continue to behave as 
described below; they are included only for compatibility with other versions of XENIX. Their use in 
new programs is strongly discouraged. 


For these signals, func is assigned one of three values: SIG_DFL, SIG_IGN, or a function address. The 
actions prescribed by these values of are as follows: 


SIG_DFL - ignore signal 
The signal is to be ignored. 


SIG_IGN - ignore signal 
The signal is to be ignored. Also, if sig is SIGCLD, the calling process’ child processes will 
not create zombie processes when they terminate; see exit(S). 


function address - catch signal 
If the signal is SIGPWR, the action to be taken is the same as that described above for func 
equal to function address. The same is true if the signal is SIGCLD except, that while the 
process is executing the signal-catching function any received SIGCLD signals will be queued 
and the signal-catching function will be continually reentered until the queue is empty. 


The SIGCLD affects two other system calls (wait(S), and exit(S)) in the following ways: 


wait If the func value of SIGCLD is set to SIG_IGN and a wait is executed, the wait will block 
until all of the calling process’ child processes terminate; it will then return a value of —1 
with errno set to ECHILD. 


exit If in the exiting process’ parent process the func value of SIGCLD is set to SIG_IGN, the exi- 
ting process will not create a zombie process. 


When processing a pipeline, the shell makes the last process in the pipeline the parent of the pro- 
ceeding processes. A process that may be piped into in this manner (and thus become the parent of 
other processes) should take care not to set SIGCLD to be caught. 


Notes 


The defined constant NSIG in signal.h standing for the number of signals is always at least one greater 
than the actual number. 


The calling process must make another call to signal after a signal is caught before another signal can 
be caught. If this is not done, subsequent signals are processed in the default manner (see the descrip- 
tion for SIG_DFL ). 
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Name 


sigsem — Signals a process waiting on a semaphore. 


Syntax 


sigsem(sem_ num); 
int sem_num; 


Description 


Sigsem signals a process that is waiting on the semaphore sem_num that it may proceed and use the 
resource governed by the semaphore. Sigsem is used in conjunction with waitsem(S) to allow synchron- 
ization of processes wishing to access a resource. One or more processes may waitsem on the given 
semaphore and will be put to sleep until the process which currently has access to the resource issues a 
sigsem call. If there are any waiting processes, sigsem causes the process which is next in line on the 
semaphore’s queue to be rescheduled for execution. The semaphore’s queue is organized in first in first 
out (FIFO) order. 


See Also 


creatsem(S), opensem(S), waitsem(S) 


Diagnostics 


Sigsem returns the value (int) -1 if an error occurs. If sem_num does not refer to a semaphore type file, 
errno is set to ENOTNAM. If sem_num has not been previously opened by opensem, errno is set to 
EBADF. If the process issuing a sigsem call is not the current “owner” of the semaphore (i.e., if the 
process has not issued a waitsem call before the sigsem), errno is set to ENAVAIL. 


Notes 


This feature is a XENIX specific enhancement and may not be present in all UNIX implementations. 
This function may be linked using the linker option - Ix. 
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Name 


sinh, cosh, tanh — Performs hyperbolic functions. 


Syntax 
#include <math.h> 


double sinh (x) 
double x; 


double cosh (x) 
double x; 


double tanh (x) 
double x; 


Description 


These functions compute the designated hyperbolic functions for real arguments. 


Diagnostics 


Sinh and cosh return a huge value of appropriate sign when the correct value would overflow. 
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Name 


sleep — Suspends execution for an interval. 


Syntax 


unsigned sleep (seconds) 
unsigned seconds; 


Description 


The current process is suspended from execution for the number of seconds specified by the argument. 
The actual suspension time may be less than that requested for because scheduled wakeups occur at 
fixed 1-second intervals, and any caught signal will terminate the sleep following execution of that 
signal’s catching routine. Also, the suspension time may be longer than requested by an arbitrary 
amount due to the scheduling of other activity in the system. The value returned by sleep will be the 
“unslept” amount (the requested time minus the time actually slept) in case the caller had an alarm set 
to go off earlier than the end of the requested sleep time, or premature arousal due to another caught 
signal. 


The routine is implemented by setting an alarm signal and pausing until it (or some other signal) occurs. 
The previous state of the alarm signal is saved and restored. The calling program may have set up an 
alarm signal before calling sleep; if the sleep time exceeds the time till such alarm signal, the process 
sleeps only until the alarm signal would have occurred, and the caller’s alarm catch routine is executed 
just before the s/eep routine returns, but if the sleep time is less than the time till such alarm, the prior 
alarm time is reset to go off at the same time it would have gone off without the intervening s/eep. 


See Also 


alarm(S), nap(S), pause(S), signal(S) 
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Name 


a 


ssignal, gsignal — Implements software signals. 


Syntax 
#include <signal.h> 


int (*ssignal (sig, action)\ ) 
int sig, (*actiony ); 


int gsignal (sig) 
int sig; 


Description 


Ssignal and gsignal implement a software facility similar to signal(S). This facility is used by the stan- 
dard C library to enable the user to indicate the disposition of error conditions, and is also made 
available to the user for his >wn purposes. 


Software signals made available to users are associated with integers in the inclusive range 1 through 15. 
An action for a software signal is established by a call to ssignal, and a software signal is raised by a 
call to gsignal. Raising a software signal causes the action established for that signal to be taken. 


The first argument to ssignal is a number identifying the type of signal for which an action is to be esta- 
blished. The second argument defines the action; it is either the name of a (user defined) action function 
or one of the manifest constants SIG DFL (default) or SIG_IGN (ignore). Ssignal returns the action 

c~ previously established for that signal type; if no action has been established or the signal number is 
illegal, ssignal returns SIG_DFL. 


Gsignal raises the signal identified by its argument, sig: 


If an action function has been established for sig, then that action is reset to SIG_DFL and the ac- 
tion function is entered with argument sig. Gsignal returns the value returned to it by the action 
function. 


If the action for sig is SIG_IGN , gsignal returns the value 1 and takes no other action. 
If the action for sig is SIG _DFL , gsignal returns the value 0 and takes no other action. 
If sig has an illegal value or no action was ever specified for sig, gsignal returns the value 0 and 
takes no other action. 
Notes 


There are some additional signals with numbers outside the range 1 through 15 that are used by the 
standard C library to indicate error conditions. Thus, some signal numbers outside the range 1 through 
15 are legal, although their use may interfere with the operation of the standard C library. 
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Name 


cy 


stat, fstat — Gets file status. 


Syntax 


#include <sys/types.h> 
#include <sys/stat.h> 


int stat (path, buf) 
char *path; 
struct stat «buf; 


int fstat (fildes, buf) 
int fildes; 
struct stat «buf; 


Description 


STAT (S) 


Path points to a pathname naming a file. Read, write or execute permission of the named file is not re- 
quired, but all directories listed in the pathname leading to the file must be searchable. Stat obtains in- 


formation about the named file. 


Similarly, fstat obtains information about an open file known by the file descriptor fildes, obtained from 


a successful open, creat, dup, fcntl, or pipe system call. 


Buf is a pointer to a stat structure into which information is placed concerning the file. 


The contents of the structure pointed to by buf include the following members: 


ushort _st_mode; /* File mode; see mknod(S) */ 
ino t __ st_ino; /* Inode number */ 
dev t st_dev; /* ID of device containing */ 


/* a directory entry for this file */ 


dev t _—_st_rdev; /* ID of device */ 


/* This entry is defined only for */ 


/* special files */ 
short st_nlink; /* Number of links */ 


ushort  st_uid; /* User ID of the file’s owner */ 
ushort _ st_gid; /* Group ID of the file’s group */ 
off t st_size; /* File size in bytes */ 

time t st_atime; /* Time of last access */ 

time t st_mtime; /* Time of last data modification */ 
time t st_ctime; /* Time of last file status change */ 


/* Times measured in seconds since */ 


/* 00:00:00 GMT, Jan. 1, 1970 */ 


st atime Time when file data was last accessed. Changed by the following system calls: creat(S), 


mknod(S), pipe(S), utime(S), and read(S). 


st mtime Time when data was last modified. Changed by the following system calls: creat(S), 


mknod(S), pipe(S), utime(S), and write(S). 


o™ st ctime Time when file status was last changed. Changed by the following system calls: chmod(S), 


chown(S), creat(S), link(S), mknod(S), pipe(S), utime(S), and write(S). 
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st_rdev Device identification. In the case of block and character special files this contains the device 
major and minor numbers; in the case of shared memory and semaphores, it contains the 
type code. The file /usr/include/sys/types.h contains the macros major() and minor() for 
extracting major and minor numbers from st_rdev. See /usr/include/sys/stat.h for the sema- 
phore and shared memory type code values S INSEM and S_INSHD. 
Stat will fail if one or more of the following are true: 
A component of the path prefix is not a directory. [ENOTDIR] 
The named file does not exist. [ENOENT] 
Search permission is denied for a component of the path prefix. [EACCES] 
Buf or path points to an invalid address. [EFAULT] 
Fstat will fail if one or more of the following are true: 


Fildes is not a valid open file descriptor. [EBADF] 


Buf points to an invalid address. [EFAULT] 


Return Value 


Upon successful completion a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


chmod(S), chown(S), creat(S), link(S), mknod(S), time(S), unlink(S) 


June 28, 1985 . Page 2 


STDIO (S) STDIO (S) 


Name 


stdio — Performs standard buffered input and output. 


Syntax 


#include <stdio.h> 
FILE «stdin, *stdout, «stderr; 


Description 


The stdio library contains an efficient, user-level I/O buffering scheme. The in-line macros getc(S) and 
putc(S) handle characters quickly. The macros getchar, putchar, and the higher-level routines fgetc, 
fgets, fprintf, fputc, fputs, fread, fscanf, fwrite, gets, getw, printf, puts, putw, and scanf all use getc 
and putc; they can be freely intermixed. 


A file with associated buffering is called a “stream” and is declared to be a pointer to a defined type 
FILE . Fopen(S) creates certain descriptive data for a stream and returns a pointer to designate the 
stream in all further transactions. Normally, there are three open streams with constant pointers de- 
clared in the “include” file and associated with the standard open files: 


stdin Standard input file 
stdout Standard output file 
stderr Standard error file 


A constant “pointer” NULL designates the null stream. 


An integer constant EOF is returned upon end-of-file or error by most integer functions that deal with 
streams (see the individual descriptions for details). 


Any program that uses this package must include the header file of pertinent macro definitions, as fol- 
lows: 


#include <stdio.h> 


Most of the functions and constants mentioned in this section of the manual are declared in that “in- 
clude” file and are described elsewhere. The constants and the following “functions” are implemented 
as macros (redeclaration of these names is perilous): getc, getchar, putc, putchar, feof, ferror, and 
fileno. 


See Also 


open(S), close(S), read(S), write(S), ctermid(S), cuserid(S), fclose(S), ferror(S), fopen(S), fread(S), 
fseek(S), getc(S), gets(S), popen(S), printf(S), putc(S), puts(S), scanf(S), setbuf(S), system(S), 
tmpnam(S) 

Diagnostics 


Invalid stream pointers can cause grave disorder, possibly including program termination. Individual 
function descriptions describe the possible error conditions. 


June 28, 1985 Page 1 


STIME (S) STIME (S) 


Name 


stime — Sets the time. 


Syntax 


#include <sys/types.h> 
#include <sys/timeb.h> 


time t stime (tp) 
long *tp; 
Description 


Stime sets the system’s idea of the time and date. Tp points to the value of time as measured in 
seconds from 00:00:00 GMT January 1, 1970. 


Stime will fail if the effective user ID of the calling process is not super-user. [EPERM] 


Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


time(S) 
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Name 


cy 


string, strcat, strncat, strcmp, strncmp, strepy, strncpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn, 
strtok, strdup — Perform string operations. 


Syntax 


char *streat (s1, s2) 
char *s1, *s2; 


char *strncat (sl, s2, n) 
char *s1, *s2; 
int n; 


int strcmp (s1, s2) 
char *sl, *s2; 


int strncmp (s1, s2, n) 
char *sl, *s2; 
int n; 


char *strepy (s1, s2) 
char *s1, *s2; 


char *strncpy (sl, s2, n) 
char «sl, *s2; 
int n; 


int strlen (s) 
char *s; 


char *strchr (s, c) 
char *s, C; 


char *strrchr (s, Cc) 
char *s, C; 


char *strpbrk (s1, s2) 
char *s1, *s2; 


int strspn (sl, s2) 
char *s1, *82; 


int strespn (sl, s2) 
char *s1, *s2; 


char *strtok (s1, s2) 
char *sl, *s2; 


char *strdup (s) 
char *s; 
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Name 


swab — Swaps bytes. 


Syntax 


swab (from, to, nbytes) 
char *from, *to; 
int nbytes; 


Description 


Swab copies nbytes pointed to by from to the position pointed to by to, exchanging adjacent even and 
odd bytes. It is useful for transporting binary data between machines that differ in the ordering of 
bytes. Nbytes should be even. 
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Name 


sync — Updates the super-block. 


Syntax 


sync ( ) 


Description 


Sync causes all information in memory that should be on disk to be written out. This includes modified 
super-blocks, modified inodes, and delayed block I/O. 


It should be used by programs which examine a file system, for example fsck, df, etc. 


The writing, although scheduled, is not necessarily complete upon return from sync. 


See Also 


sync(C) 
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Name 


system — Executes a shell command. 


Syntax 
#include <stdio.h> 
int system (string) 
char «string; 
Description 


System causes the string to be given to sh(C) as input as if the string had been typed as a command at 
a terminal. The current process waits until the shell has completed, then returns the exit status of the 
shell. 


See Also 


sh(C), exec(S) 


Diagnostics 


System stops if it can’t execute sh(C). 
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Name 


tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs — Performs terminal functions. 


Syntax 


char PC; 
char *BC; 
char *UP; 
short ospeed; 


tgetent(bp, name) 
char *bp, *name; 


tgetnum(id) 
char *id; 


tgetflag(id) 
char *id; 


char * 
tgetstr(id, area) 
char *id, **area; 


char * 
tgoto(cm, destcol, destline) 
char *cm; 


tputs(cp, affcnt, outc) 
register char *cp; 

int affcnt; 

int (*outc\); 


Description 


These functions extract and use capabilities from the terminal capability data base termcap(F). These 
are low level routines; see curses(S) for a higher level package. 


Tgetent extracts the entry for terminal name into the buffer at bp. Bp should be a character buffer of 
size 1024 and must be retained through all subsequent calls to tgetnum, tgetflag, and tgetstr. Tgetent re- 
turns —1 if it cannot open the termcap file, 0 if the terminal name given does not have an entry, and 1 if 
all goes well. It will look in the environment for a TERMCAP variable. If found, and the value does 
not begin with a slash, and the terminal type name is the same as the environment string TERM, the 
TERMCAP string is used instead of reading the termcap file. If it does begin with a slash, the string is 
used as a pathname rather than /etc/termcap. This can speed up entry into programs that call tgetent, as 
well as to help debug new terminal descriptions or to make one for your terminal if you can’t write the 
file /etc/termcap. 


Tgetnum gets the numeric value of capability id, returning —1 if is not given for the terminal. Tgetflag 
returns 1 if the specified capability is present in the terminal’s entry, 0 if it is not. Tgetstr gets the 
string value of capability id, placing it in the buffer at area, advancing the area pointer. It decodes the 
abbreviations for this field described in termcap(F), except for cursor addressing and padding informa- 
tion. 


Tgoto returns a cursor addressing string decoded from cm to go to column @estcol in line destline. It 
uses the external variables UP (from the up capability) and BC (if be is given rather than bs) if 
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necessary to avoid placing \n, CNTRL-D or NULL in the returned string. (Programs which call tgoto 
should be sure to turn off the TAB3 bit (see tty(M)), since tgoto may now output a tab. Note that pro- 
grams using termcap should in general turn off TAB3 anyway since some terminals use CNTRL-I for 
other functions, such as nondestructive space.) If a % sequence is given which is not understood, then 
tgoto returns OOPS. 


Tputs decodes the leading padding information of the string cp; affcnt gives the number of lines affected 
by the operation, or 1 if this is not applicable, outc is a routine which is called with each character in 
turn. The external variable ospeed should contain the output speed of the terminal as encoded by stty 
(S). The external variable PC should contain a pad character to be used (from the pe capability) if a 
NULL is inappropriate. 


Files 
/usr/lib/libtermcap.a —Iltermcap library 
/etc/termcap data base 

See Also 


curses(S), termcap(F), tty(M) 


Credit 


This utility was developed at the University of California at Berkeley and is used with permission. 


Notes 


These routines can be linked by using the linker option —Itermcap. 
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Name 


time, ftime — Gets time and date. 


Syntax 


long time ((long *) 0) 


long time (tloc) 
long *tloc; 


#include <sys/types.h> 
#include <sys/timeb.h> 


ftime(tp) 
struct timeb *tp; 


Description 


Time returns the current system time in seconds since 00:00:00 GMT, January 1, 1970. 


If tloc (taken as an integer) is nonzero, the return value is also stored in the location to which floc 
points. 


Ftime returns the time in a structure (see below under Return Value.) 


Time will fail if tloc points to an illegal address. [EFAULT] Likewise, ftime will fail if tp points to an 
illegal address. [EFAULT] 


Return Value 


Upon successful completion, time returns the value of time. Otherwise, a value of —1 is returned and 
errno is set to indicate the error. 


The ftime entry fills in a structure pointed to by its argument, as defined by <sys/timeb.h>: 
{* 
* Structure returned by ftime system call 
* 
struct timeb { 
long time; 
unsigned short millitm; 
short timezone; 


short dstflag; 
}; 
Note that the timezone value is a system default timezone and not the value of the TZ environment 


variable. 


The structure contains the time since the epoch in seconds, up to 1000 milliseconds of more-precise in- 
terval, the local time zone (measured in minutes of time westward from Greenwich), and a flag that, if 
nonzero, indicates that Daylight Saving time applies locally during the appropriate part of the year. 
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See Also 
date(C), stime(S), ctime(S) 


Notes 


Since ftime does not return the correct timezone value, its use is not recommended. See ctime(S) for 
accurate use of the TZ variable. This routine may be linked using the linker option - Ix. 
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Name 


times — Gets process and child process times. 


Syntax 


#include <sys/types.h> 
#include <sys/times.h> 


time t times(tp) 
struct tms *tp; 
Description 


Times fills the structure pointed to by buffer with time-accounting information. This information comes 
from the calling process and each of its terminated child processes for which it has executed a wait(S). 


All times are in clock ticks where a tick is some fraction of a second defined in machine (M). 
tms_utime is the CPU time used while executing instructions in the user space of the calling process. 
tms_sStime is the CPU time used by the system on behalf of the calling process. 

tms_cutime is the sum of the utimes and cutimes of the child processes. 

tms_cstime is the sum of the stimes and cstimes of the child processes. 


Times will fail if buffer points to an illegal address. [EFAULT] 


Return Value 


Upon successful completion, times returns the elapsed real time, in clock ticks, since an arbitrary point 
in the past, such as the system start-up time. This point does not change from one invocation of times 
to another. If times fails, a —1 is returned and errno is set to indicate the error. 


See Also 


exec(S), fork(S), time(S), wait(S), machine(M) 
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Name 


tmpfile — Creates a temporary file. 


Syntax 
#include <stdio.h> 


FILE *tmpfile () 


Description 


Tmpfile creates a temporary file and returns a corresponding FILE pointer. Arrangements are made so 
that the file will automatically be deleted when the process using it terminates. The file is opened for 
update. 


See Also 


creat(S), unlink(S), fopen(S), mktemp(S), tmpnam(S) 
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Name 


tmpnam — Creates a name for a temporary file. 


Syntax 


#include <stdio.h> 


char *tmpnam (s) 
char *s; 


Description 


Tmpnam generates a filename that can safely be used for a temporary file. If (int)s is zero, tmpnam 
leaves its result in an internal static area and returns a pointer to that area. The next call to tmpnam 
will destroy the contents of the area. If (int)s is nonzero, s is assumed to be the address of an array of 
at least L_tmpnam bytes; tmpnam places its result in that array and returns s as its value. 


Tmpnam generates a different filename each time it is called. 


Files created using tmpnam and either fopen or creat are only temporary in the sense that they reside in 
a directory intended for temporary use, and their names are unique. It is the user’s responsibility to use 
unlink (S) to remove the file when its use is ended. 


See Also 


creat(S), unlink(S), fopen(S), mktemp(S) 


Notes 


If called more than 17,576 times in a single process, tmpnam will start recycling previously used names. 


Between the time a filename is created and the file is opened, it is possible for some other process to 
create a file with the same name. This can never happen if that other process is using tmpnam or 
mktemp, and the filenames are chosen so as to render duplication by other means unlikely. 
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Name 


c 


sin, cos, tan, asin, acos, atan, atan2 — Performs trigonometric functions. 


Syntax 
#include <math.h> 


double sin (x) 
double x; 


double cos (x) 
double x; 


double asin (x) 
double x; 


double acos (x) 
double x; 


double atan (x) 
double x; 


double atan2 (y, x) 
double x, y; 


Description 
fy 


Sin, cos and tan return trigonometric functions of radian arguments. The magnitude of the argument 
should be checked by the caller to make sure the result is meaningful. 


Asin returns the arc sin in the range —7/2 to 7/2. 
Acos returns the arc cosine in the range 0 to m. 
Atan returns the arc tangent of x in the range —7/2 to 7/2. 


Atan2 returns the arc tangent of y/x in the range —z to m. 


Diagnostics 


Arguments of magnitude greater than 1 cause asin and acos to return value 0. 


Notes 


These routines can be linked with the linker option —Im. 
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Name 


ttyname, isatty — Finds the name of a terminal. 


Syntax 
char *ttyname (fildes) 


int isatty (fildes) 


Description 


Ttyname returns a pointer to the null-terminated pathname of the terminal device associated with file 
descriptor fildes. 


Isatty returns | if fildes is associated with a terminal device, 0 otherwise. 


Files 


/dev/* 


Diagnostics 


Ttyname returns a null pointer (0) if fildes does not describe a terminal device in directory /dev. 


Notes 


The return value points to static data whose content is overwritten by each call. 


June 28, 1985 Page 1 


ULIMIT (S) | ULIMIT (S) 


Name 


ulimit — Gets and sets user limits. 


Syntax 


#include <sys/ulimit.h> 
long ulimit (cmd, newlimit) 
int cmd; 

long newlimit; 


Description 


This function provides for control over process limits. The cmd values available are: 


UL_GFILLIM | 
Gets the process’ file size limit. The limit is in units of 512-byte blocks and is inherited by child 
processes. Files of any size can be read. 


UL_SFILLIM 
Sets the process’ file size limit to the value of newlimit. Any process may decrease this limit, but 
only a process with an effective user ID of super-user may increase the limit. Ulimit will fail and 
the limit will be unchanged if a process with an effective user ID other than super-user attempts to 
increase its file size limit. [EPERM] 


UL_GMEMLIM 
Gets the maximum possible break value. If the process is a large model 80286 program, then the 
largest possible data size (in bytes) is returned. See sbrk(S). 


UL_GTXTOFF 
Gets the number of bytes between the beginning of user text and the text address given by newl- 
imit. In this case, newlimit must have type 


int (*newlimity); 
Return Value 
Upon successful completion, a nonnegative value is returned. Otherwise, a value of —1 is returned and 
errno is set to indicate the error. EINVAL indicates an invalid cmd value. 
See Also 


sbrk(S), chsize(S), write(S) 
Notes 


The file limit is only enforced on writes to regular files. Tapes, disks, and other devices of any size can 
be written. 
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Name 


umask — Sets and gets file creation mask. 


Syntax 
int umask (cmask) 
int cmask; 
Description 
Umask sets the process’ file mode creation mask to cmask and returns the previous value of the mask. 
Only the low-order 9 bits of cmask and the file mode creation mask are used. 
Return Value 


The previous value of the file mode creation mask is returned. 


See Also 
mkdir(C), mknod(C), sh(C), chmod(S), mknod(S), open(S) 
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Name 


umount — Unmounts a file system. 


Syntax 
int umount (spec) 
char *spec; 
Description 


Umount requests that a previously mounted file system contained on the block special device identified 
by spec be unmounted. Spec is a pointer to a pathname. After unmounting the file system, the direc- 
tory upon which the file system was mounted reverts to its ordinary interpretation. 


Umount may be invoked only by the super-user. 
Umount will fail if one or more of the following are true: 
The process’ effective user ID is not super-user. [EPERM] 
Spec does not exist. [ENXIO] 
Spec is not a block special device. [ENOTBLK] 
Spec is not mounted. [EINVAL] 
A file on spec is busy. [EBUSY] 


Spec points outside the process’ allocated address space. [EFAULT] 


Return Value 


Upon successful completion a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


mount(C), mount(S) 
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Name 


uname — Gets name of current XENIX system. 


Syntax 
#include <sys/utsname.h> 


int uname (name) 
struct utsname *name; 


Description 


Uname stores information identifying the current XENIX system in the structure pointed to by name. 
Uname uses the structure defined in <sys/utsname.h>: 


struct utsname { 
char  sysname([9]; 
char nodename(9]; 
char ___ release[9]; 
char _ version[9]; 
unsigned short sysorigin; 
unsigned short sysoem; 
long __ sysserial; 
if 
Uname returns a null-terminated character string naming the current XENIX system in the character 
array sysname. Similarly, nodename contains the name that the system is known by on a communica- 
tions network. Release and version further identify the operating system. Sysorigin and syseom iden- 
tify the source of the XENIX version. Sysserial is a software serial number which may be zero if 


unused. 


Uname will fail if name points to an invalid address. [EFAULT] 


Return Value 


Upon successful completion, a nonnegative value is returned. Otherwise, —1 is returned and errno is set 
to indicate the error. 


See Also 


uname(C) 


Notes 
Not all fields may be set on a particular system. 


This function is a XENIX specific enhancement and may not be present on all UNIX implementations. 
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Name 


ungetc — Pushes character back into input stream. 


Syntax 
#include <stdio.h> 


int ungetc (c, stream) 
char c; 
FILE *stream; 


Description 


Ungetc pushes the character c back on an input stream. The character will be returned by the next getc 
call on that stream. Ungetc returns c. 


One character of pushback is guaranteed provided something has been read from the stream and the 
stream is actually buffered. Attempts to push EOF are rejected. 


Fseek(S) erases all memory of pushed back characters. 


See Also 


fseek(S), getc(S), setbuf(S) 


a 


Diagnostics 


Ungetc returns EOF if it can’t push a character back. 
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Name 


unlink — Removes directory entry. 


Syntax 
int unlink (path) 
char *path; 
Description 
Unlink removes the directory entry named by the pathname pointed to by path. 
The named file is unlinked unless one or more of the following are true: 
A component of the path prefix is not a directory. [ENOTDIR] 
The named file does not exist. [ENOENT] 
Search permission is denied for a component of the path prefix. [EACCES] 
Write permission is denied on the directory containing the link to be removed. [EACCES] 
The named file is a directory and the effective user ID of the process is not super-user. [EACCES] 
The entry to be unlinked is the mount point for a mounted file system. [EBUSY] 
The entry to be unlinked is “.” or “..” in the root directory of a mounted filesystem. [EBUSY] 


The entry to be unlinked is the last link to a pure procedure (shared text) file that is being executed. 
[ETXTBSY] 


The directory entry to be unlinked is part of a read-only file system. [EROFS] 
Path points outside the process’ allocated address space. [EFAULT] 


When all links to a file have been removed and no process has the file open, the space occupied by the 
file is freed and the file ceases to exist. If one or more processes have the file open when the last link is 
removed, the removal is postponed until all references to the file have been closed. 


Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


rm(C), close(S), link(S), open(S) 
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Name 


ustat — Gets file system statistics. 


Syntax 


#include <sys/types.h> 
#include <ustat.h> 


int ustat (dev, buf) 
int dev; 
struct ustat «buf; 


Description 


Ustat returns information about a mounted file system. Dev is a device number identifying a device 
containing a mounted file system. Buf is a pointer to a ustat structure that includes the following ele- 


ments: 
daddr t f_tfree; /* Total free blocks */ 
ino t f_tinode; /* Number of free inodes */ 
char f fname[6]; /* Filsys name */ 
char f fpack[6]; /* Filsys pack name */ 


Ustat will fail if one or more of the following are true: 
Dev is not the device number of a device containing a mounted file system. [EINVAL] 


Buf points outside the process’ allocated address space. [EFAULT] 


Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 


See Also 


stat(S), filesystem(F) 
Notes 


When using file systems from previous versions of XENIX, fsck(C) must be run on the file system before 
mounting. Otherwise the ustat system call will not work correctly. This only needs to be done once. 
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Name 


utime — Sets file access and modification times. 


Syntax 


#include <sys/types.h> 
int utime (path, times) 
char *path; 

struct utimbuf «times; 


Description 


Path points to a pathname naming a file. Utime sets the access and modification times of the named 
file. 


If times is NULL, the access and modification times of the file are set to the current time. A process 
must be the owner of the file or have write permission to use utime in this manner. 


If times is not NULL, times is interpreted as a pointer to a utimbuf structure and the access and modifi- 
cation times are set to the values contained in the designated structure. Only the owner of the file or 
the super-user may use utime this way. 


The times in the following structure are measured in seconds since 00:00:00 GMT, Jan. 1, 1970. 


struct utimbuf { 
time t actime; /* access time */ 
time t modtime; /* modification time */ 


}; 
Utime will fail if one or more of the following are true: 
The named file does not exist. [ENOENT] 
A component of the path prefix is not a directory. [ENOTDIR] 
Search permission is denied by a component of the path prefix. [EACCES] 


The effective user ID is not super-user and not the owner of the file and times is not NULL. 
[EPERM] 


The effective user ID is not super-user and not the owner of the file and times is NULL and write 
access is denied. [EACCES] 


The file system containing the file is mounted read-only. [EROFS] 
Times is not NULL and points outside the process’ allocated address space. [EFAULT] 


Path points outside the process’ allocated address space. [EFAULT] 


Return Value 


Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is 
set to indicate the error. 
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Name 


wait — Waits for a child process to stop or terminate. 


Syntax 


int wait (stat loc) 
int *stat_loc; 


int wait ((int *)0) 


Description 


Wait suspends the calling process until it receives a signal that is to be caught (see signal(S)), or until 
any one of the calling process’ child processes stops in a trace mode (see ptrace(S)) or terminates. If a 
child process stopped or terminated prior to the call on wait, return is immediate. 


If stat_loc (taken as an integer) is nonzero, 16 bits of information called “status” are stored in the low- 
order 16 bits of the location pointed to by stat_loc. Status can be used to differentiate between stopped 
and terminated child processes and if the child process terminated, status identifies the cause of termina- 
tion and passes useful information to the parent. This is accomplished in the following manner: 


If the child process stopped, the high-order 8 bits of status will be zero and the low-order 8 bits will 
be set equal to 0177. 


If the child process terminated due to an exit call, the low-order 8 bits of status will be zero and the 
high-order 8 bits will contain the low-order 8 bits of the argument that the child process passed to 
exit; see exit(S). 


If the child process terminated due to a signal, the high-order 8 bits of status will be zero and the 
low-order 8 bits will contain the number of the signal that caused the termination. In addition, if the 
low-order seventh bit (i.e., bit 200) is set, a “core image” will have been produced; see signal(S). 


If a parent process terminates without waiting for its child processes to terminate, the parent process ID 
of each child process is set to 1. This means the initialization process inherits the child processes; see 
intro(S). 


Wait will fail and return immediately if one or more of the following are true: 
The calling process has no existing unwaited-for child processes. [ECHILD] 


Stat_loc points to an illegal address. [EFAULT] 


Return Value 


If wait returns due to the receipt of a signal, a value of —1 is returned to the calling process and errno is 
set to EINTR. If wait returns due to a stopped or terminated child process, the process ID of the child is 
returned to the calling process. Otherwise, a value of —1 is returned and errno is set to indicate the 


error. 


See Also 


exec(S), exit(S), fork(S), pause(S), signal(S) 
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Warning 


See Warning in signal(S). 
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Name 


waitsem, nbwaitsem — Awaits and checks access to a resource governed by a semaphore. 


Syntax 


waitsem(sem_ num); 
int sem_num; 


nbwaitsem(sem_ num); 
int sem_num; 


Description 


Waitsem gives the calling process access to the resource governed by the semaphore sem_num. If the 
resource is in use by another process, waitsem will put the process to sleep until the resource becomes 
available; nbwaitsem will return the error ENAVAIL. Waitsem and nbwaitsem are used in conjunction 
with sigsem to allow synchronization of processes wishing to access a resource. One or more processes 
may waitsem on the given semaphore and will be put to sleep until the process which currently has 
access to the resource issues sigsem. Sigsem causes the process which is next in line on the semaphore’s 
queue to be rescheduled for execution. The semaphore’s queue is organized in first in first out (FIFO) 


order. 


See Also 


creatsem(S), opensem(S), sigsem(S) 


Diagnostics 


Waitsem returns the value (int) -1 if an error occurs. If sem_num has not been previously opened by a 
call to opensem or creatsem, errno is set to EBADF. If sem_num does not refer to a semaphore type file, 
errno is set to ENOTNAM. AIl processes waiting (or attempting to wait) on the semaphore when the 
process controlling the semaphore exits without relinquishing control (thereby leaving the resource in an 
undeterminate state) return with errno set to ENAVAIL. If a process does two waitsems in a row 
without doing an intervening sigsem errno is set to EINVAL. 


Notes 


This feature is a XENIX specific enhancement and may not be present in all UNIX implementations. 
This routine may be linked with the linker option - Ix. 
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Name 


write — Writes to a file. 


Syntax 


int write (fildes, buf, nbyte) 
int fildes; 

char *buf; 

unsigned nbyte; 


Description 


Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system call. 


Write attempts to write nbyte bytes from the buffer pointed to by buf to the file associated with the 
fildes. 


On devices capable of seeking, the actual writing of data proceeds from the position in the file indicated 
by the file pointer. Upon return from write, the file pointer is incremented by the number of bytes actu- 
ally written. 


On devices incapable of seeking, writing always takes place starting at the current position. The value 
of a file pointer associated with such a device is undefined. 


If the O APPEND flag of the file status flags is set, the file pointer will be set to the end of the file prior 
to each write. 


Write will fail and the file pointer will remain unchanged if one or more of the following are true: 
Fildes is not a valid file descriptor open for writing. [EBADF] 


An attempt is made to write to a pipe that is not open for reading by any process. [EPIPE and SIG- 
PIPE signal] 


An attempt was made to write a file that exceeds the process’ file size limit or the maximum file 
size. See ulimit(S). [EFBIG] 


Buf points outside the process’ allocated address space. [EFAULT] 


If a write requests that more bytes be written than there is room for (e.g., the ulimit (see ulimit(S)) or 
the physical end of a medium), only as many bytes as there is room for will be written. For example, 
suppose there is space for 20 bytes more in a file before reaching a limit. A write of 512 bytes will re- 
turn 20. The next write of a nonzero number of bytes will give a failure return (except as noted below). 


If the file being written is a pipe (or FIFO), no partial writes will be permitted. Thus, the write will fail 
if a write of nbyte bytes would exceed a limit. 


If the file being written is a pipe (or FIFO) and the O NDELAY flag of the file flag word is set, then 
write to a full pipe (or FIFO) will return a count of 0. Otherwise (O NDELAY clear), writes to a full 
pipe (or FIFO) will block until space becomes available. 
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Return Value 


Upon successful completion the number of bytes actually written is returned. Otherwise, —1 is returned Ww 
and errno is set to indicate the error. 


See Also 
creat(S), dup(S), lseek(S), open(S), pipe(S), ulimit(S) 


Notes 


Writing a region of a file locked with locking or lockf causes write to hang indefinitely until the locked 
region is unlocked. 
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INTRO (F) INTRO (F) 


Name 


intro — Introduction to file formats. 
Description 


This section outlines the formats of various files. Usually, these structures can be found in the direc- 
tories /usr/include or /usr/include/sys. 
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Name 
a 


a.out — Format of assembler and link editor output. 


Description 


A.out is the output file of the assembler as and the link editor /d. Both programs will make a.out execu- 
table if there were no errors in assembling or linking, and no unresolved external references. 


The format of a.out, called the x.out or segmented x.out format, is defined by the files 
/usr/include/a.out.h and /usr/include/sys/relsym.h. The a.out file has the following general layout: 


lL, Header. 

2. Extended header. 

3. File segment table (for segmented formats). 

4. Segments (Text, Data, Symbol, and Relocation). 


In the segmented format, there may be several text and data segments, depending on the memory model 
of the program. Segments within the file begin on boundaries which are multiplies of 512 bytes as 
defined by the file’s pagesize. 


See Also 


as(CP), ld(CP), nm(CP), strip(CP). 
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Name 


acct — Format of per-process accounting file. 


Description 


Files produced as a result of calling acct(S) have records in the form defined by <sys/acct.h>. 


In ac_flag, the AFORK flag is turned on by each fork(S) and turned off by an exec(S). The ac_comm 
field is inherited from the parent process and is reset by any exec. Each time the system charges the 
process with a clock tick, it also adds the current process size to ac_mem computed as follows: 


(data size) + (text size) / (number of in-core processes using text) 
The value of ac mem/ac_stime can be viewed as an approximation to the mean process size, as modified 
by text-sharing. 
See Also 


acct(C), acctcom(C), acct(S) 


Notes 


The ac_mem value for a short-lived command gives little information about the actual size of the com- 
mand, because ac_mem may be incremented while a different command (e.g., the shell) is being exe- 
cuted by the process. 
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Name 


ar — Archive file format. 


Description 


The archive command ar is used to combine several files into one. Archives are used mainly as libraries 
to be searched by the link editor /d(C). 


A file produced by ar has a magic number at the start, followed by the constituent files, each preceded 
by a file header. The magic number is 0177545 octal (or Oxff65 hexadecimal). The header of each file 
is declared in /usr/include/ar.h. 


Each file begins on a word boundary; a null byte is inserted between files if necessary. Nevertheless the 
size given reflects the actual size of the file exclusive of padding. 


Notice there is no provision for empty areas in an archive file. 


See Also 


ar(CP), Id(CP) 
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Name 


backup — Incremental dump tape format. 


Description 


The backup and restore commands are used to write and read incremental dump magnetic tapes. 


The backup tape consists of a header record, some bit mask records, a group of records describing file 
system directories, a group of records describing file system files, and some records describing a second 
bit mask. 


The header record and the first record of each description have the format described by the structure in- 
cluded by: 


#include <dumprestor.h> 
Fields in the dumprestor structure are described below. 


NTREC is the number of 512 byte blocks in a physical tape record. MLEN is the number of bits in a bit 
map word. MSIZ is the number of bit map words. 


The TS_ entries are used in the c_ type field to indicate what sort of header this is. The types and their 
meanings are as follows: 


TS_TYPE Tape volume label. 


TS_INODE _ A file or directory follows. The c_dinode field is a copy of the disk inode and contains bits 
telling what sort of file this is. 


TS_ BITS A bit mask follows. This bit mask has one bit for each inode that was backed up. 
TS ADDR A subblock to a file (TS_INODE). See the description of c_count below. 
TS_END End of tape record. 


TS_CLRI A bit mask follows. This bit mask contains one bit for all inodes that were empty on the 
file system when backed up. 


MAGIC All header blocks have this number in c_magic. 
CHECKSUM Header blocks checksum to this value. 


The fields of the header structure are as follows: 


c type The type of the header. 

c date The date the backup was taken. 

c ddate The date the file system was backed up. 

c volume The current volume number of the backup. 

c tapea The current block number of this record. This is counting 512 byte blocks. 


¢ inumber The number of the inode being backed up if this is of type TS_INODE. 
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c magic 
c checksum 
c dinode 


c count 


c addr 


BACKUP (F) 


This contains the value MAGIC above, truncated as needed. 
This contains whatever value is needed to make the block sum to CHECKSUM. 
This is a copy of the inode as it appears on the file system. 


This is the count of characters following that describe the file. A character is zero if the 
block associated with that character was not present on the file system, otherwise the 
character is nonzero. If the block was not present on the file system no block was backed 
up and it is replaced as a hole in the file. If there is not sufficient space in this block to 
describe all of the blocks in a file, TS ADDR blocks will be scattered through the file, 
each one picking up where the last left off. 


This is the array of characters that is used as described above. 


Each volume except the last ends with a tapemark (read as an end of file). The last volume ends with a 
TS END block and then the tapemark. 


The structure idates describes an entry of the file where backup history is kept. 


See Also 


backup(C), restore(C), filesystem(F) 
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Name 


checklist — List of file systems processed by fsck. 


Description 


The /etc/checklist file contains a list of the file systems to be checked when fsck(C) is invoked without 
arguments. The list contains at most 15 special file names. Each special file name must be on a 
separate line and must correspond to a file system. 


See Also 


fsck(C) 
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Name 


—_ core — Format of core image file. 


Description 


XENIX writes out a core image of a terminated process when any of various errors occur. See signal(S) 
for the list of reasons; the most common are memory violations, illegal instructions, bus errors, and 
user-generated quit signals. The core image is called core and is written in the process’ working direc- 
tory (provided it can be; normal access controls apply). A process with an effective user ID different 
from the real user ID will not produce a core image. 


The first section of the core image is a copy of the system’s per-user data for the process, including the 
registers as they were at the time of the fault. The size of this section depends on the parameter usize, 
which is defined in /usr/include/sys/param.h. The remainder represents the actual contents of the 
user’s core area when the core image was written. If the text segment is read-only and shared, or 
separated from data space, it is not dumped. 


The format of the information in the first section is described by the user structure of the system, de- 
fined in /usr/include/sys/user.h. The locations of registers, are outlined in /usr/include/sys/reg.h. 


See Also 


adb(CP), setuid(S), signal(S) 
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Name 


— cpio — Format of cpio archive. 


Description 


The header structure, when the ¢c option is not used, is: 


struct { 
short h magic, 
h_ dev, 
h_ino, 
h mode, 
h_uid, 
h gid, 
h_nlink, 
h_rdev, 
h mtime[2], 
h_ namesize, 
h _filesize[2]; 
char kh name[h namesize rounded to word]; 
} Hdr; 


When the c option is used, the header information is described by the statement below: 


sscanf(Chdr,"%60%60%60%60%60%60%60%60% 1 110%60%60%s", 
&Hdr.h magic,&Hdr.h dev,&Hdr.h_ino,&Hdr.h_ mode, 
oc &Hdr.h uid,&Hdr.h_gid,& Hdr.h_nlink, & Hdr.h_rdev, 
wy & Longtime, & Hdr.h_namesize, & Longfile,Hdr.h_name); 


Longtime and Longfile are equivalent to Hdr.h_mtime and Hdr.h_filesize, respectively. The contents of 
each file is recorded in an element of the array of varying length structures, archive, together with other 
items describing the file. Every instance of h_magic contains the constant 070707 (octal). The items 
h_dev through h_mtime have meanings explained in stat(S). The length of the null-terminated path- 
name h_name, including the null byte, is given by h_namesize. 


The last record of the archive always contains the name TRAILER!!!. Special files, directories, and the 
trailer are recorded with h_filesize equal to zero. 


See Also 


cpio(C), find(C), stat(S) 
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Name 


dir — Format of a directory. 


Syntax 


#include <sys/dir.h> 


Description 


A directory behaves exactly like an ordinary file, except that no user may write into a directory. The 
fact that a file is a directory is indicated by a bit in the flag word of its inode entry (see filesystem(F)). 
The structure of a directory is given in the include file /usr/include/sys/dir.h. 


By convention, the first two entries in each directory are“dot” (.) and “dotdot” (..). The first is an entry 
for the directory itself. The second is for the parent directory. The meaning of dotdot is modified for 
the root directory of the master file system; there is no parent, so dotdot has the same meaning as dot. 


See Also 


filesystem(F) 
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Name 


dump — Incremental dump tape format. 


Description 
The dump and restor commands are used to write and read incremental dump magnetic tapes. 


The dump tape consists of a header record, some bit mask records, a group of records describing file 
system directories, a group of records describing file system files, and some records describing a second 
bit mask. 


The header record and the first record of each description have the format described by the structure in- 
cluded by: 


#include <dumprestor.h> 
Fields in the dumprestor structure are described below. 


NTREC is the number of 512 byte blocks in a physical tape record. MLEN is the number of bits in a bit 
map word. MSIZ is the number of bit map words. 


The TS_ entries are used in the c_type field to indicate what sort of header this is. The types and their 
meanings are as follows: 


TS TYPE Tape volume label. 


TS INODE _ AA file or directory follows. The c_ dinode field is a copy of the disk inode and contains bits 
telling what sort of file this is. 


TS BITS A bit mask follows. This bit mask has a one bit for each inode that was dumped. 
TS ADDR A subblock to a file (TS_INODE). See the description of c_ count below. 
TS_ END End of tape record. 


TS _CLRI A bit mask follows. This bit mask contains a one bit for all inodes that were empty on 
the file system when dumped. 


MAGIC All header blocks have this number in c_ magic. 
CHECKSUM Header blocks checksum to this value. 


The fields of the header structure are as follows: 


c type The type of the header. 

c date The date the dump was taken. 

c ddate The date the file system was dumped from. 

c volume The current volume number of the dump. 

c tapea The current block number of this record. This is counting 512 byte blocks. 


¢ inumber The number of the inode being dumped if this is of type TS INODE. 
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c magic This contains the value MAGIC above, truncated as needed. 
c checksum This contains whatever value is needed to make the block sum to CHECKSUM. 
c dinode This is a copy of the inode as it appears on the file system. 


c count This is the count of characters following that describe the file. A character is zero if the 
block associated with that character was not present on the file system, otherwise the 
character is nonzero. If the block was not present on the file system no block was 
dumped and it is replaced as a hole in the file. If there is not sufficient space in this 
block to describe all of the blocks in a file, TS_ADDR blocks will be scattered through the 
file, each one picking up where the last left off. 


c addr This is the array of characters that is used as described above. 


Each volume except the last ends with a tapemark (read as an end of file). The last volume ends with a 
TS_END block and then the tapemark. 


The structure idates describes an entry of the file where dump history is kept. 


See Also 


dump(C), restor(C), filesystem(F) 
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Name 


file system — Format of a system volume. 


Syntax 


#include <sys/filsys.h> 
#include <sys/types.h> 
#include <sys/param.h> 


Description 


Every file system storage volume (e.g., a hard disk) has a common format for certain vital information. 
Every such volume is divided into a certain number of 256 word (512 byte) blocks. Block 0 is unused 
and is available to contain a bootstrap program or other information. 


Block 1 is the super-block. The format of a super-block is described in /usr/include/sys/filesys.h. In 
that include file, S isize is the address of the first data block after the i-list. The i-list starts just after 
the super-block in block 2; thus the i-list is s_isize—2 blocks long. S_fsize is the first block not poten- 
tially available for allocation to a file. These numbers are used by the system to check for bad block 
numbers. If an “impossible” block number is allocated from the free list or is freed, a diagnostic is 
written on the console. Moreover, the free array is cleared so as to prevent further allocation from a 
presumably corrupted free list. 


The free list for each volume is maintained as follows. The s_free array contains, in s free[1], ..., 
s_free[s nfree—1], up to 49 numbers of free blocks. S_free[0] is the block number of the head of a 
chain of blocks constituting the free list. The first long in each free-chain block is the number (up to 
50) of free-block numbers listed in the next 50 longs of this chain member. The first of these 50 blocks 
is the link to the next member of the chain. To allocate a block: decrement s_nfree, and the new block 
is s_free[s_nfree]. If the new block number is 0, there are no blocks left, so give an error. If s_nfree 
becomes 0, read in the block named by the new block number, replace s_nfree by its first word, and 
copy the block numbers in the next 50 longs into the s_free array. To free a block, check if s_nfree is 
50; if so, copy s_nfree and the s_free array into it, write it out, and set s nfree to 0. In any event set 
s_free|s_nfree] to the freed block’s number and increment s_nfree. 


S_tfree is the total free blocks available in the file system. 


S_ninode is the number of free i-numbers in the s inode array. To allocate an inode: if s_ninode is 
greater than 0, decrement it and return s inode[s_ninode|. If it was 0, read the i-list and place the 
numbers of all free inodes (up to 100) into the s_ inode array, then try again. To free an inode, provided 
s_ninode is less than 100, place its number into s inode[s_ninode] and increment s_ninode. If s_ninode 
is already 100, do not bother to enter the freed inode into any table. This list of inodes only speeds up 
the allocation process. The information about whether the inode is really free is maintained in the inode 
itself. 


S_tinode is the total free inodes available in the file system. 


S_flock and s_ilock are flags maintained in the core copy of the file system while it is mounted and 
their values on disk are immaterial. The value of s_fmod on disk is also immaterial, and is used as a 
flag to indicate that the super-block has changed and should be copied to the disk during the next 
periodic update of file system information. 


S_ronly is a read-only flag to indicate write-protection. 


S time is the last time the super-block of the file system was changed, and is a double-precision 
representation of the number of seconds that have elapsed since 00:00 Jan. 1, 1970 (GMT). During a 
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reboot, the s_time of the super-block for the root file system is used to set the system’s idea of the time. 

I-numbers begin at 1, and the storage for inodes begins in block 2. Also, inodes are 64 bytes long, so 8 
of them fit into a block. Therefore, inode i is located in block (i+15)/8, and begins 64x((i+15) (mod 
8)) bytes from its start. Inode 1 is reserved for future use. Inode 2 is reserved for the root directory of 


the file system, but no other i-number has a built-in meaning. Each inode represents one file. For the 
format of an inode and its flags, see inode(F). 


Files 
/usr/include/sys/filsys.h 


/usr/include/sys/stat.h 


See Also 


fsck(C), mkfs(C), inode(F) 
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Name 


inode — Format of an inode. 


Syntax 


#include <sys/types.h> 
#include <sys/ino.h> 


Description 


An inode for a plain file or directory in a file system has the structure defined by <sys/ino.h>. For the 
meaning of the defined types off t and time_t see types(F). 


Files 


/usr/include/sys/ino.h 


See Also 


stat(S), filesystem(F), types(F) 
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Name 


a 


master — Master device information table. 


Description 


This file is used by the config(CP) program to obtain device information that enables it to generate the 
configuration files. The file consists of 4 parts, each separated by a line with a dollar sign ($) in column 
1. Part 1 contains device information; part 2 contains the line discipline table; part 3 contains names of 
devices that have aliases; and part 4 contains tunable parameter information. Any line with an asterisk 
(+) in column | is treated as a comment. 


Part 1 


This part contains definitions for the system devices. Each line has 14 fields with the fields delimited by 
tabs and/or blanks: 


Field 1: device name (8 chars. maximum). 
Field 2: interrupt vector size (decimal, in bytes). 
Field 3: device mask (octal). Each “on” bit indicates that the driver has the corresponding 


handler or structure: 
000400 not used 
000200 not used 
000100 initialization handler 
000040 not used 
000020 open handler 
om 000010 close handler 
X 7 000004 read handler 
000002 write handler 
000001 ioctl handler. 
Field 4: device type indicator (octal): 
000200 allow only one of these devices 
000100 not used 
000040 not used 
000020 required device 
000010 block device 
000004 character device 
000002 not used 
000001 not used. 


Field 5: handler prefix (4 chars. maximum). 

Field 6: not used. 

Field 7: major device number for block-type device. 

Field 8: major device number for character-type device. 

Field 9: maximum number of devices per controller (decimal). 


Field 10: not used. 
Fields 11-14: maximum of four interrupt vector addresses. Each address is followed by a unique 
letter or a blank. 


Devices that are not interrupt-driven have an interrupt vector size of zero. Devices which generate inter- 
rupts but are not of the standard character or block device mold, should be specified with a type (field 4) 
which has neither the block nor character bits set. 
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Part 2 


This part contains definitions for the system line discipline. Each line has 11 fields. Each field is a max- 
imum of 8 characters delimited by a blank if less than 8: 


Field 1: 

Device associated with this line 
Field 2: 

open routine 
Field 3: 

close routine 
Field 4: 

read routine 
Field 5: 

write routine 
Field 6: 

ioctl routine 
Field 7: 

receiver interupt routine 
Field 8: 

unused — should be “nulldev”’ 
Field 9: 

unused — should be “‘nulldev”’ 
Field 10: 

output start routine 
Field 11: 


9 


unused — should be “nulldev’ 


Part 3 
This part contains definitions for device aliases. Each line has 2 fields: 


Field 1: alias name of device (8 chars. maximum). 
Field 2: reference name of device as given in part 1 (8 chars. maximum). 


Aliases may be used in place of actual device names when creating the config (CP) description file. 


Part 4 


This part contains the names and default values for tunable parameters. Each line has 2 or 3 fields: 


Field 1: parameter name to be used in the config(CP) description file (20 chars. maximum) 
Field 2: parameter name as it will appear in the resulting c.c file (20 chars. maximum) 
Field 3: default parameter value (20 chars. maximum) 


If a parameter has no default value, an explicit specification for the parameter must be given in the 
description file. See config(CP) for a list of the tunable parameters. 


See Also 


config(CP) 
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Notes 
| Master is not supported on 8086 based machines. 
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Name 


mnttab — Format of mounted file system table. 


Syntax 
#include <stdio.h> 
#include <mnttab.h> 
Description 
The /etc/mnttab file contains a table of devices mounted by the mount(C) command. 


Each table entry contains the pathname of the directory on which the device is mounted, the name of 
the device special file, the read/write permissions of the special file, and the date on which the device 
was mounted. 


The maximum number of entries in mnttab is based on the system parameter NMOUNT located in 
/usr/sys/conf/c.c, which defines the number of allowable mounted special files. 


See Also 


mount(C) 
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Name 


Cy 


sccsfile — Format of an SCCS file. 


Description 


An SCCS file is an ASCII file. It consists of six logical parts: the checksum, the delta table (contains 
information about each delta), user names (contains login names and/or numerical group IDs of users 
who may add deltas), flags (contains definitions of internal keywords), comments (contains arbitrary 
descriptive information about the file), and the body (contains the actual text lines intermixed with con- 
trol lines). Each logical part of an SCCS file is described in detail below. 


Throughout an SCCS file there are lines which begin with the ASCII SOH (start of heading) character 
(octal 001). This character is hereafter referred to as the control character and will be represented 
graphically as @. Any line described below which is not depicted as beginning with the control 
character is prevented from beginning with the control character. Entries of the form DDDDD represent 
a five digit string (a number between 00000 and 99999). 


Checksum 


The checksum is the first line of an SCCS file. The form of the line is: 
@hDDDDD 


The value of the checksum is the sum of all characters, except those of the first line. The @hR provides 
a magic number of (octal) 064001. 


o "Delta Table" 


The delta table consists of a variable number of entries of the form: 
@s DDDDD/DDDDD/DDDDD 
@d <type> <SCCSID> yr/mo/da hr:mi:se <pgmr> DDDDD DDDDD 
(@i DDDDD ... 
(@x DDDDD ... 
(@g DDDDD ... 
(@m <MR number> 


(@c <comments> ... 


@e 
The first line (@s) contains the number of lines inserted/deleted/unchanged respectively. The second 
line (@d) contains the type of the delta (currently, normal: D, and removed: R), the SCCS ID of the 


delta, the date and time of creation of the delta, the login name corresponding to the real user ID at the 
time the delta was created, and the serial numbers of the delta and its predecessor, respectively. 


The @i, @x, and (@g lines contain the serial numbers of deltas included, excluded, and ignored, respec- 
tively. These lines are optional. 


The @m lines (optional) each contain one MR number associated with the delta; the @c lines contain 
comments associated with the delta. 


The @e line ends the delta table entry. 
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User Names 


The list of login names and/or numerical group IDs of users who may add deltas to the file, separated Uo 
by new-lines. The lines containing these login names and/or numerical group IDs are surrounded by the 
bracketing lines @u and @U. An empty list allows anyone to make a delta. 


Flags 


Keywords used internally (see admin(CP) for more information on their use). Each flag line takes the 
form: 


@f <flag> <optional text> 
The following flags are defined: 


@ft  <type of program> 
(@fv <program name> 


(@f i 

(@fb 

@fm <module name> 
@ff  <floor> 


@fc <ceiling> 
@f{d <default-sid> 
@fn 

@f j 

@f1 <lock-releases> 
@fq <user defined> Y 
The t flag defines the replacement for the identification keyword. The v flag controls prompting for 

MR numbers in addition to comments; if the optional text is present it defines an MR number validity 

checking program. The i flag controls the warning/error aspect of the “No id keywords” message. 

When the i flag is not present, this message is only a warning; when the i flag is present, this message 

will cause a “fatal” error (the file will not be gotten, or the delta will not be made). When the b flag is 

present the —b option may be used with the get command to cause a branch in the delta tree. The m 

flag defines the first choice for the replacement text of the sccsfile.F identification keyword. The f flag 

defines the “floor” release; the release below which no deltas may be added. The c flag defines the “cei- 

ling” release; the release above which no deltas may be added. The d flag defines the default SID to be 

used when none is specified on a get command. The n flag causes delta to insert a “null” delta (a delta 

that applies no changes) in those releases that are skipped when a delta is made in a new release (e.g., 

when delta 5.1 is made after delta 2.7, releases 3 and 4 are skipped). The absence of the n flag causes 

skipped releases to be completely empty. The j flag causes get to allow concurrent edits of the same 

base SID. The I flag defines a /ist of releases that are locked against editing (get(CP) with the —e op- 

tion). The q flag defines the replacement for the identification keyword. 


Comments 


Arbitrary text surrounded by the bracketing lines @t and @T. The comments section typically contains 
a description of the file’s purpose. 


Body 


The body consists of text lines and control lines. Text lines don’t begin with the control character, con- a 
trol lines do. There are three kinds of control lines: insert, delete, and end, as follows: 
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@I DDDDD 
@D DDDDD 
@E DDDDD 


The digit string (DDDDD) is the serial number corresponding to the delta for the control line. 


See Also 


admin(CP), delta(CP), get(CP), prs(CP) 


Xenix Programmer's Guide 
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Name 


STAT (F) 


stat — Data returned by stat system call. 


Syntax 


#include <sys/stat.h> 


Description 


The sys/stat.h include file contains the definition for the structure returned by the stat and fstat func- 
tions. The structure is defined as: 


struct stat{ 


dev t st_ dev; 


ino t st_ino; 
ushort —sh_mode; 
short st_nlink; 


ushort __ st_uid; 
ushort _ st_ gid; 
dev t st_rdev; 
off t st size; 
time t _—_st_atime; 
time t —_ st_mtime; 
time t _—_st_ctime; 


}; 


/* id of device containing directory entry */ 
/* inode number */ 

/* file mode */ 

/* # of links */ 

/* owner uid */ 

/* owner gid */ 

/* device id (block and char devices only) */ 
/* file size in bytes */ 

/* time of last access */ 

/* time of last data modification */ 

/* time of last file status ’change’ */ 


Note that the st_atime, st_mtime, and st_ctime values are measured in seconds since 00:00:00 (GMT) 
on January 1, 1970. 


The st_mode value is actually a combination of one or more of the following file mode values: 


S IFMT 
S IFDIR 
S IFCHR 
S IFBLK 
S IFREG 
S_IFIFO 
S_IFNAM 

S_INSEM 

S INSHD 

S ISUID 

S IGUID 

S ISVTX 

S IREAD 

S IWRITE 

S IEXEC 


Files 


0170000 
0040000 
0020000 
0060000 
0100000 
0010000 
0050000 
01 

02 
04000 
02000 
01000 
00400 
00200 
00100 


/usr/include/sys/stat.h 


See Also 


stat(S) 


September 7, 1984 


/* type of file */ 

j? awectoty */ 

/* character special */ 

/* block special */ 

/* regular */ 

PP Tio?) 

/* name special entry */ 

/* semaphore */ 

/* shared memory */ 

/* set user id on execution */ 

/* set group id on execution */ 

/* save swapped text even after use */ 
/* read permission, owner */ 

/* write permission, owner */ 

/* execute/search permission, owner */ 
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Name 


types — Primitive system data types. 


Syntax 


#include <sys/types.h> 


Description 


The data types defined in the include file <sys/types.h> are. used in XENIX system code; some data of 
these types are accessible to user code. 


The form daddr t is used for disk addresses except in an inode on disk, see filesystem(F). Times are 
encoded in seconds since 00:00:00 GMT, January 1, 1970. The major and minor parts of a device code 
specify kind and unit number of a device and are installation-dependent. Offsets are measured in bytes 
from the beginning of a file. The /abel_t variables are used to save the processor state while another 
process is running. 


See Also 


filesystem(F) 
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